xml-twig 1.7.12 → 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

@@ -33,7 +33,7 @@
 ## Functions
 
 <dl>
-<dt><a href="#createParser">createParser(handler, [options])</a> ⇒ <code><a href="#Parser">Parser</a></code></dt>
+<dt><a href="#createParser">createParser(handler, options)</a> ⇒ <code><a href="#Parser">Parser</a></code></dt>
 <dd><p>Create a new Twig parser</p>
 </dd>
 <dt><a href="#onStart">onStart(parser, binds, node, attrs)</a></dt>
@@ -120,7 +120,7 @@ You can specify a <code>function</code> or a <code>event</code> name</p>
 
 * [Twig](#Twig)
     * [new Twig()](#new_Twig_new)
-    * [new Twig(parser, name, [parent], [attributes], [index])](#new_Twig_new)
+    * [new Twig(parser, name, parent, attributes, index)](#new_Twig_new)
     * [.attributes](#Twig+attributes) : <code>object</code> ℗
     * [.text](#Twig+text) : <code>string</code> \| <code>number</code> ℗
     * [.name](#Twig+name) : <code>string</code> ℗
@@ -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)
@@ -176,8 +178,8 @@ You can specify a <code>function</code> or a <code>event</code> name</p>
     * [.addElement](#Twig+addElement) ⇒ [<code>Twig</code>](#Twig)
     * [.delete](#Twig+delete)
     * [.setRoot(name)](#Twig+setRoot) ℗
-    * [.filterElements(elements, [condition])](#Twig+filterElements) ⇒ [<code>Array.&lt;Twig&gt;</code>](#Twig)
-    * [.testElement(element, [condition])](#Twig+testElement) ⇒ <code>boolean</code>
+    * [.filterElements(elements, condition)](#Twig+filterElements) ⇒ [<code>Array.&lt;Twig&gt;</code>](#Twig)
+    * [.testElement(element, condition)](#Twig+testElement) ⇒ <code>boolean</code>
 
 <a name="new_Twig_new"></a>
 
@@ -186,7 +188,7 @@ Generic class modeling a XML Node
 
 <a name="new_Twig_new"></a>
 
-### new Twig(parser, name, [parent], [attributes], [index])
+### new Twig(parser, name, parent, attributes, index)
 Create a new Twig object
 
 
@@ -194,9 +196,9 @@ Create a new Twig object
 | --- | --- | --- |
 | parser | [<code>Parser</code>](#Parser) | The main parser object |
 | name | <code>string</code> | The name of the XML element |
-| [parent] | [<code>Twig</code>](#Twig) | The parent object |
-| [attributes] | <code>object</code> | Attribute object |
-| [index] | <code>string</code> \| <code>number</code> | Position name 'first', 'last' or the position in the current `children` array.<br>Defaults to 'last' |
+| parent | [<code>Twig</code>](#Twig) | The parent object |
+| attributes | <code>object</code> | Attribute object |
+| index | <code>string</code> \| <code>number</code> | Position name 'first', 'last' or the position in the current `children` array.<br>Defaults to 'last' |
 
 <a name="Twig+attributes"></a>
 
@@ -249,13 +251,14 @@ 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)  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [elt] | [<code>Twig</code>](#Twig) | Up to this element the tree will be purged. If `undefined` then the current element is purged (i.e. `purge()`) |
+| elt | [<code>Twig</code>](#Twig) | Up to this element the tree will be purged. If `undefined` then the current element is purged (i.e. `purge()`) |
 
 <a name="Twig+escapeEntity"></a>
 
@@ -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,14 +411,15 @@ 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  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>AttributeCondition</code>](#AttributeCondition) | Optional condition to select attribute |
+| condition | [<code>AttributeCondition</code>](#AttributeCondition) | Optional condition to select attribute |
 
 <a name="Twig+attributes"></a>
 
@@ -444,12 +450,15 @@ Retrieve or update XML attribute. For update, the condition must be a string, i.
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>AttributeCondition</code>](#AttributeCondition) | Optional condition to select attributes |
-| [value] | <code>string</code> \| <code>number</code> \| <code>bigint</code> \| <code>boolean</code> | New value of the attribute.<br>If `undefined` then existing attributes is returned. |
+| condition | [<code>AttributeCondition</code>](#AttributeCondition) | Optional condition to select attributes |
+| value | <code>string</code> \| <code>number</code> \| <code>bigint</code> \| <code>boolean</code> | New value of the attribute.<br>If `undefined` then existing attributes is returned. |
 
 **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>
 
@@ -490,7 +499,29 @@ All children, optionally matching `condition` of the current element or empty ar
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| 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>
 
@@ -503,7 +534,7 @@ Returns the next matching element.
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+previous"></a>
 
@@ -516,7 +547,7 @@ Returns the previous matching element.
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+first"></a>
 
@@ -528,7 +559,7 @@ Returns the first matching element. This is usually the root element
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+last"></a>
 
@@ -540,7 +571,7 @@ Returns the last matching element.
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+isFirstChild"></a>
 
@@ -566,7 +597,7 @@ Returns descendants (children, grandchildren, etc.) of the current element
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+descendantOrSelf"></a>
 
@@ -578,7 +609,7 @@ Returns descendants (children, grandchildren, etc.) of the current element and t
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+ancestor"></a>
 
@@ -590,7 +621,7 @@ Returns ancestors (parent, grandparent, etc.)  of the current element
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+ancestorOrSelf"></a>
 
@@ -602,7 +633,7 @@ Returns ancestors (parent, grandparent, etc.)  of the current element and the cu
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+sibling"></a>
 
@@ -614,7 +645,7 @@ Returns all sibling element of the current element
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+siblingOrSelf"></a>
 
@@ -626,7 +657,7 @@ Returns all sibling element of the current element and the current element itsel
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+followingSibling"></a>
 
@@ -638,7 +669,7 @@ Returns all following sibling element of the current element
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+precedingSibling"></a>
 
@@ -650,7 +681,7 @@ Returns all preceding sibling element of the current element
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+nextSibling"></a>
 
@@ -662,7 +693,7 @@ Returns next sibling element of the current element
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+prevSibling"></a>
 
@@ -674,7 +705,7 @@ Returns previous sibling element of the current element
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+find"></a>
 
@@ -699,9 +730,9 @@ Add a new element in the current element
 | Param | Type | Description |
 | --- | --- | --- |
 | name | <code>string</code> | The tag name |
-| [text] | <code>string</code> | Text of the element |
-| [attributes] | <code>object</code> | Element attributes |
-| [position] | <code>name</code> \| <code>number</code> | Position name 'first', 'last' or the position in the `children` |
+| text | <code>string</code> | Text of the element |
+| attributes | <code>object</code> | Element attributes |
+| position | <code>name</code> \| <code>number</code> | Position name 'first', 'last' or the position in the `children` |
 
 <a name="Twig+delete"></a>
 
@@ -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  
@@ -723,7 +755,7 @@ Sets the name of root element. In some cases the root is created before the XML-
 
 <a name="Twig+filterElements"></a>
 
-### twig.filterElements(elements, [condition]) ⇒ [<code>Array.&lt;Twig&gt;</code>](#Twig)
+### twig.filterElements(elements, condition) ⇒ [<code>Array.&lt;Twig&gt;</code>](#Twig)
 Common function to filter Twig elements from array
 
 **Kind**: instance method of [<code>Twig</code>](#Twig)  
@@ -732,11 +764,11 @@ Common function to filter Twig elements from array
 | Param | Type | Description |
 | --- | --- | --- |
 | elements | [<code>Twig</code>](#Twig) \| [<code>Array.&lt;Twig&gt;</code>](#Twig) | Array of elements you like to filter or a single element |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | The filter condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | The filter condition |
 
 <a name="Twig+testElement"></a>
 
-### twig.testElement(element, [condition]) ⇒ <code>boolean</code>
+### twig.testElement(element, condition) ⇒ <code>boolean</code>
 Common function to filter Twig element
 
 **Kind**: instance method of [<code>Twig</code>](#Twig)  
@@ -745,7 +777,7 @@ Common function to filter Twig element
 | Param | Type | Description |
 | --- | --- | --- |
 | element | [<code>Twig</code>](#Twig) | Element you like to filter |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | The filter condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | The filter condition |
 
 <a name="Twig"></a>
 
@@ -754,7 +786,7 @@ Common function to filter Twig element
 
 * [Twig](#Twig)
     * [new Twig()](#new_Twig_new)
-    * [new Twig(parser, name, [parent], [attributes], [index])](#new_Twig_new)
+    * [new Twig(parser, name, parent, attributes, index)](#new_Twig_new)
     * [.attributes](#Twig+attributes) : <code>object</code> ℗
     * [.text](#Twig+text) : <code>string</code> \| <code>number</code> ℗
     * [.name](#Twig+name) : <code>string</code> ℗
@@ -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)
@@ -810,8 +844,8 @@ Common function to filter Twig element
     * [.addElement](#Twig+addElement) ⇒ [<code>Twig</code>](#Twig)
     * [.delete](#Twig+delete)
     * [.setRoot(name)](#Twig+setRoot) ℗
-    * [.filterElements(elements, [condition])](#Twig+filterElements) ⇒ [<code>Array.&lt;Twig&gt;</code>](#Twig)
-    * [.testElement(element, [condition])](#Twig+testElement) ⇒ <code>boolean</code>
+    * [.filterElements(elements, condition)](#Twig+filterElements) ⇒ [<code>Array.&lt;Twig&gt;</code>](#Twig)
+    * [.testElement(element, condition)](#Twig+testElement) ⇒ <code>boolean</code>
 
 <a name="new_Twig_new"></a>
 
@@ -820,7 +854,7 @@ Generic class modeling a XML Node
 
 <a name="new_Twig_new"></a>
 
-### new Twig(parser, name, [parent], [attributes], [index])
+### new Twig(parser, name, parent, attributes, index)
 Create a new Twig object
 
 
@@ -828,9 +862,9 @@ Create a new Twig object
 | --- | --- | --- |
 | parser | [<code>Parser</code>](#Parser) | The main parser object |
 | name | <code>string</code> | The name of the XML element |
-| [parent] | [<code>Twig</code>](#Twig) | The parent object |
-| [attributes] | <code>object</code> | Attribute object |
-| [index] | <code>string</code> \| <code>number</code> | Position name 'first', 'last' or the position in the current `children` array.<br>Defaults to 'last' |
+| parent | [<code>Twig</code>](#Twig) | The parent object |
+| attributes | <code>object</code> | Attribute object |
+| index | <code>string</code> \| <code>number</code> | Position name 'first', 'last' or the position in the current `children` array.<br>Defaults to 'last' |
 
 <a name="Twig+attributes"></a>
 
@@ -883,13 +917,14 @@ 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)  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [elt] | [<code>Twig</code>](#Twig) | Up to this element the tree will be purged. If `undefined` then the current element is purged (i.e. `purge()`) |
+| elt | [<code>Twig</code>](#Twig) | Up to this element the tree will be purged. If `undefined` then the current element is purged (i.e. `purge()`) |
 
 <a name="Twig+escapeEntity"></a>
 
@@ -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,14 +1077,15 @@ 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  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>AttributeCondition</code>](#AttributeCondition) | Optional condition to select attribute |
+| condition | [<code>AttributeCondition</code>](#AttributeCondition) | Optional condition to select attribute |
 
 <a name="Twig+attributes"></a>
 
@@ -1078,12 +1116,15 @@ Retrieve or update XML attribute. For update, the condition must be a string, i.
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>AttributeCondition</code>](#AttributeCondition) | Optional condition to select attributes |
-| [value] | <code>string</code> \| <code>number</code> \| <code>bigint</code> \| <code>boolean</code> | New value of the attribute.<br>If `undefined` then existing attributes is returned. |
+| condition | [<code>AttributeCondition</code>](#AttributeCondition) | Optional condition to select attributes |
+| value | <code>string</code> \| <code>number</code> \| <code>bigint</code> \| <code>boolean</code> | New value of the attribute.<br>If `undefined` then existing attributes is returned. |
 
 **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>
 
@@ -1124,7 +1165,29 @@ All children, optionally matching `condition` of the current element or empty ar
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| 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>
 
@@ -1137,7 +1200,7 @@ Returns the next matching element.
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+previous"></a>
 
@@ -1150,7 +1213,7 @@ Returns the previous matching element.
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+first"></a>
 
@@ -1162,7 +1225,7 @@ Returns the first matching element. This is usually the root element
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+last"></a>
 
@@ -1174,7 +1237,7 @@ Returns the last matching element.
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+isFirstChild"></a>
 
@@ -1200,7 +1263,7 @@ Returns descendants (children, grandchildren, etc.) of the current element
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+descendantOrSelf"></a>
 
@@ -1212,7 +1275,7 @@ Returns descendants (children, grandchildren, etc.) of the current element and t
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+ancestor"></a>
 
@@ -1224,7 +1287,7 @@ Returns ancestors (parent, grandparent, etc.)  of the current element
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+ancestorOrSelf"></a>
 
@@ -1236,7 +1299,7 @@ Returns ancestors (parent, grandparent, etc.)  of the current element and the cu
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+sibling"></a>
 
@@ -1248,7 +1311,7 @@ Returns all sibling element of the current element
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+siblingOrSelf"></a>
 
@@ -1260,7 +1323,7 @@ Returns all sibling element of the current element and the current element itsel
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+followingSibling"></a>
 
@@ -1272,7 +1335,7 @@ Returns all following sibling element of the current element
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+precedingSibling"></a>
 
@@ -1284,7 +1347,7 @@ Returns all preceding sibling element of the current element
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+nextSibling"></a>
 
@@ -1296,7 +1359,7 @@ Returns next sibling element of the current element
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+prevSibling"></a>
 
@@ -1308,7 +1371,7 @@ Returns previous sibling element of the current element
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
 <a name="Twig+find"></a>
 
@@ -1333,9 +1396,9 @@ Add a new element in the current element
 | Param | Type | Description |
 | --- | --- | --- |
 | name | <code>string</code> | The tag name |
-| [text] | <code>string</code> | Text of the element |
-| [attributes] | <code>object</code> | Element attributes |
-| [position] | <code>name</code> \| <code>number</code> | Position name 'first', 'last' or the position in the `children` |
+| text | <code>string</code> | Text of the element |
+| attributes | <code>object</code> | Element attributes |
+| position | <code>name</code> \| <code>number</code> | Position name 'first', 'last' or the position in the `children` |
 
 <a name="Twig+delete"></a>
 
@@ -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  
@@ -1357,7 +1421,7 @@ Sets the name of root element. In some cases the root is created before the XML-
 
 <a name="Twig+filterElements"></a>
 
-### twig.filterElements(elements, [condition]) ⇒ [<code>Array.&lt;Twig&gt;</code>](#Twig)
+### twig.filterElements(elements, condition) ⇒ [<code>Array.&lt;Twig&gt;</code>](#Twig)
 Common function to filter Twig elements from array
 
 **Kind**: instance method of [<code>Twig</code>](#Twig)  
@@ -1366,11 +1430,11 @@ Common function to filter Twig elements from array
 | Param | Type | Description |
 | --- | --- | --- |
 | elements | [<code>Twig</code>](#Twig) \| [<code>Array.&lt;Twig&gt;</code>](#Twig) | Array of elements you like to filter or a single element |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | The filter condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | The filter condition |
 
 <a name="Twig+testElement"></a>
 
-### twig.testElement(element, [condition]) ⇒ <code>boolean</code>
+### twig.testElement(element, condition) ⇒ <code>boolean</code>
 Common function to filter Twig element
 
 **Kind**: instance method of [<code>Twig</code>](#Twig)  
@@ -1379,7 +1443,7 @@ Common function to filter Twig element
 | Param | Type | Description |
 | --- | --- | --- |
 | element | [<code>Twig</code>](#Twig) | Element you like to filter |
-| [condition] | [<code>ElementCondition</code>](#ElementCondition) | The filter condition |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | The filter condition |
 
 <a name="NotImplementedYet"></a>
 
@@ -1446,7 +1510,7 @@ Generic error for unsupported condition
 
 ## SAX
 **Kind**: global constant  
-**Version:**: 1.7.11  
+**Version:**: 1.9.0  
 **Author:**: Wernfried Domscheit  
 **Copyright:**: Copyright (c) 2025 Wernfried Domscheit. All rights reserved.  
 **Website:**: https://www.npmjs.com/package/xml-twig  
@@ -1460,7 +1524,7 @@ Generic error for unsupported condition
 **Kind**: global constant  
 <a name="createParser"></a>
 
-## createParser(handler, [options]) ⇒ [<code>Parser</code>](#Parser)
+## createParser(handler, options) ⇒ [<code>Parser</code>](#Parser)
 Create a new Twig parser
 
 **Kind**: global function  
@@ -1473,7 +1537,7 @@ Create a new Twig parser
 | Param | Type | Description |
 | --- | --- | --- |
 | handler | [<code>TwigHandler</code>](#TwigHandler) \| [<code>Array.&lt;TwigHandler&gt;</code>](#TwigHandler) | Object or array of element specification and function to handle elements |
-| [options] | [<code>ParserOptions</code>](#ParserOptions) | Object of optional options |
+| options | [<code>ParserOptions</code>](#ParserOptions) | Object of optional options |
 
 <a name="onStart"></a>
 
@@ -1515,12 +1579,12 @@ Optional settings for the Twig parser
 
 | Name | Type | Description |
 | --- | --- | --- |
-| [method] | <code>&#x27;sax&#x27;</code> \| <code>&#x27;expat&#x27;</code> | The underlying parser. Either `'sax'`, `'expat'`. |
-| [xmlns] | <code>boolean</code> | If `true`, then namespaces are accessible by `namespace` property. |
-| [trim] | <code>boolean</code> | If `true`, then turn any whitespace into a single space. Text and comments are trimmed. |
-| [resumeAfterError] | <code>boolean</code> | If `true` then parser continues reading after an error. Otherwise it throws exception. |
-| [partial] | <code>boolean</code> | If `true` then unhandled elements are purged. |
-| [file] | <code>string</code> | Optional. The name of file to be parsed. Just used for information and logging purpose. |
+| method | <code>&#x27;sax&#x27;</code> \| <code>&#x27;expat&#x27;</code> | The underlying parser. Either `'sax'`, `'expat'`. |
+| xmlns | <code>boolean</code> | If `true`, then namespaces are accessible by `namespace` property. |
+| trim | <code>boolean</code> | If `true`, then turn any whitespace into a single space. Text and comments are trimmed. |
+| resumeAfterError | <code>boolean</code> | If `true` then parser continues reading after an error. Otherwise it throws exception. |
+| partial | <code>boolean</code> | If `true` then unhandled elements are purged. |
+| file | <code>string</code> | Optional. The name of file to be parsed. Just used for information and logging purpose. |
 
 **Example**  
 ```js
@@ -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**
@@ -1537,13 +1603,19 @@ Reference to handler functions for Twig objects.<br>
 | Name | Type | Description |
 | --- | --- | --- |
 | tag | [<code>HandlerCondition</code>](#HandlerCondition) | Element specification |
-| [function] | [<code>HandlerFunction</code>](#HandlerFunction) | Definition of handler function, either anonymous or explicit function |
-| [event] | <code>string</code> | Type of the event to be emitted |
+| function | [<code>HandlerFunction</code>](#HandlerFunction) | Definition of handler function, either anonymous or explicit function |
+| event | <code>string</code> | Type of the event to be emitted |
 
 <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>
@@ -1597,16 +1674,20 @@ Custom filter function to select desired elements
 
 | Name | Type | Description |
 | --- | --- | --- |
-| [currentLine] | <code>number</code> | The currently processed line in the XML-File. |
-| [currentColumn] | <code>number</code> | The currently processed column in the XML-File. |
-| [file] | <code>string</code> | The name of file to be parsed. Just used for information and logging purpose. |
-| [twig] | <code>object</code> | Object with XML tree and current XML element |
-| [method] | <code>string</code> | The underlying parser. Either `'sax'`, `'expat'`. |
+| currentLine | <code>number</code> | The currently processed line in the XML-File. |
+| currentColumn | <code>number</code> | The currently processed column in the XML-File. |
+| file | <code>string</code> | The name of file to be parsed. Just used for information and logging purpose. |
+| twig | <code>object</code> | Object with XML tree and current XML element |
+| method | <code>string</code> | The underlying parser. Either `'sax'`, `'expat'`. |
 
 <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.12",
+  "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.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
@@ -62,12 +62,12 @@ const Any = new AnyHandler();
 /**
 * Optional settings for the Twig parser
 * @typedef ParserOptions 
-* @property {'sax' | 'expat'} [method] - The underlying parser. Either `'sax'`, `'expat'`.
-* @property {boolean} [xmlns] - If `true`, then namespaces are accessible by `namespace` property.
-* @property {boolean} [trim] - If `true`, then turn any whitespace into a single space. Text and comments are trimmed.
-* @property {boolean} [resumeAfterError] - If `true` then parser continues reading after an error. Otherwise it throws exception.
-* @property {boolean} [partial] - If `true` then unhandled elements are purged.
-* @property {string} [file] - Optional. The name of file to be parsed. Just used for information and logging purpose.
+* @property {'sax' | 'expat'} method - The underlying parser. Either `'sax'`, `'expat'`.
+* @property {boolean} xmlns - If `true`, then namespaces are accessible by `namespace` property.
+* @property {boolean} trim - If `true`, then turn any whitespace into a single space. Text and comments are trimmed.
+* @property {boolean} resumeAfterError - If `true` then parser continues reading after an error. Otherwise it throws exception.
+* @property {boolean} partial - If `true` then unhandled elements are purged.
+* @property {string} [file - Optional. The name of file to be parsed. Just used for information and logging purpose.
 * @example { method: 'expat', xmlns: true }
 * @default  { method: 'sax', xmlns: false, trim: true, resumeAfterError: false, partial: false }
 */
@@ -78,8 +78,8 @@ const Any = new AnyHandler();
 * You can specify a `function` or a `event` name
 * @typedef TwigHandler
 * @property {HandlerCondition} tag - Element specification
-* @property {HandlerFunction} [function] - Definition of handler function, either anonymous or explicit function
-* @property {string} [event] - Type of the event to be emitted
+* @property {HandlerFunction} function - Definition of handler function, either anonymous or explicit function
+* @property {string} event - Type of the event to be emitted
 */
 
 /**
@@ -126,18 +126,18 @@ const Any = new AnyHandler();
 
 /**
 * @typedef Parser
-* @property {number} [currentLine] - The currently processed line in the XML-File.
-* @property {number} [currentColumn] - The currently processed column in the XML-File.
-* @property {string} [file] - The name of file to be parsed. Just used for information and logging purpose.
-* @property {object} [twig] - Object with XML tree and current XML element
-* @property {string} [method] - The underlying parser. Either `'sax'`, `'expat'`.
+* @property {number} currentLine - The currently processed line in the XML-File.
+* @property {number} currentColumn - The currently processed column in the XML-File.
+* @property {string} file - The name of file to be parsed. Just used for information and logging purpose.
+* @property {object} twig - Object with XML tree and current XML element
+* @property {string} method - The underlying parser. Either `'sax'`, `'expat'`.
 * @returns {external:sax|external:node-expat} The parser Object
 */
 
 /**
 * Create a new Twig parser
 * @param {TwigHandler|TwigHandler[]} handler - Object or array of element specification and function to handle elements
-* @param {ParserOptions} [options] - Object of optional options 
+* @param {ParserOptions} options - Object of optional options 
 * @throws {UnsupportedParser} - For an unsupported parser. Currently `expat` and `sax` (default) are supported.
 * @returns {Parser} The parser Object
 */
@@ -517,9 +517,9 @@ class Twig {
    * Create a new Twig object
    * @param {Parser} parser - The main parser object
    * @param {?string} name - The name of the XML element
-   * @param {Twig} [parent] - The parent object
-   * @param {object} [attributes] - Attribute object
-   * @param {string|number} [index] - Position name 'first', 'last' or the position in the current `children` array.<br>Defaults to 'last'
+   * @param {Twig} parent - The parent object
+   * @param {object} attributes - Attribute object
+   * @param {string|number} index - Position name 'first', 'last' or the position in the current `children` array.<br>Defaults to 'last'
    */
    constructor(parser, name, parent, attributes, index) {
       if (index === undefined)
@@ -564,7 +564,7 @@ class Twig {
    /**
    * 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())`
-   * @param {Twig} [elt] - Up to this element the tree will be purged.
+   * @param {Twig} elt - Up to this element the tree will be purged.
    * If `undefined` then the current element is purged (i.e. `purge()`)
    */
    purgeUpTo = function (elt) {
@@ -797,7 +797,7 @@ class Twig {
    /**
    * Returns attribute value or `null` if not found.<br>
    * If more than one  matches the condition, then it returns object as [attribute()](#attribute)
-   * @param {AttributeCondition} [condition] - Optional condition to select attribute
+   * @param {AttributeCondition} condition - Optional condition to select attribute
    * @returns {?string|number|object} - The value of the attribute or `null` if the  does not exist
    */
    attr = function (condition) {
@@ -827,8 +827,8 @@ class Twig {
 
    /**
    * Retrieve or update XML attribute. For update, the condition must be a string, i.e. must match to one attribute only.
-   * @param {AttributeCondition} [condition] - Optional condition to select attributes
-   * @param {string|number|bigint|boolean} [value] - New value of the attribute.<br>If `undefined` then existing attributes is returned.
+   * @param {AttributeCondition} condition - Optional condition to select attributes
+   * @param {string|number|bigint|boolean} value - New value of the attribute.<br>If `undefined` then existing attributes is returned.
    * @returns {object} Attributes or `null` if no matching attribute found
    * @example attribute((name, val) => { return name === 'age' && val > 50})
    * attribute((name) => { return ['firstName', 'lastName'].includes(name) })
@@ -906,7 +906,7 @@ class Twig {
    /**
    * Common function to filter Twig elements from array
    * @param {Twig|Twig[]} elements - Array of elements you like to filter or a single element
-   * @param {ElementCondition} [condition] - The filter condition
+   * @param {ElementCondition} condition - The filter condition
    * @returns {Twig[]} List of matching elements or empty array
    */
    filterElements(elements, condition) {
@@ -931,7 +931,7 @@ class Twig {
    /**
    * Common function to filter Twig element
    * @param {Twig} element - Element you like to filter
-   * @param {ElementCondition} [condition] - The filter condition
+   * @param {ElementCondition} condition - The filter condition
    * @returns {boolean} `true` if the condition matches
    */
    testElement(element, condition) {
@@ -951,16 +951,36 @@ class Twig {
 
    /**
    * All children, optionally matching `condition` of the current element or empty array 
-   * @param {ElementCondition} [condition] - Optional condition
+   * @param {ElementCondition} condition - Optional condition
    * @returns {Twig[]} 
    */
    children = function (condition) {
       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
+   * @param {ElementCondition} condition - Optional condition
    * @returns {?Twig} - The next element
    * @see https://www.w3.org/TR/xpath-datamodel-31/#document-order
    */
@@ -986,7 +1006,7 @@ class Twig {
 
    /**
    * Returns the previous matching element. 
-   * @param {ElementCondition} [condition] - Optional condition
+   * @param {ElementCondition} condition - Optional condition
    * @returns {?Twig} - The previous element
    * @see https://www.w3.org/TR/xpath-datamodel-31/#document-order
    */
@@ -1007,7 +1027,7 @@ class Twig {
 
    /**
    * Returns the first matching element. This is usually the root element
-   * @param {ElementCondition} [condition] - Optional condition
+   * @param {ElementCondition} condition - Optional condition
    * @returns {?Twig} - The first element
    */
    first = function (condition) {
@@ -1018,7 +1038,7 @@ class Twig {
 
    /**
    * Returns the last matching element. 
-   * @param {ElementCondition} [condition] - Optional condition
+   * @param {ElementCondition} condition - Optional condition
    * @returns {?Twig} - The last element
    */
    last = function (condition) {
@@ -1061,7 +1081,7 @@ class Twig {
 
    /**
    * Returns descendants (children, grandchildren, etc.) of the current element
-   * @param {ElementCondition} [condition] - Optional condition
+   * @param {ElementCondition} condition - Optional condition
    * @returns {Twig[]} - Array of descendants or empty array 
    */
    descendant = function (condition) {
@@ -1075,7 +1095,7 @@ class Twig {
 
    /**
    * Returns descendants (children, grandchildren, etc.) of the current element and the current element itself
-   * @param {ElementCondition} [condition] - Optional condition
+   * @param {ElementCondition} condition - Optional condition
    * @returns {Twig[]} - Array of descendants or empty array 
    */
    descendantOrSelf = function (condition) {
@@ -1089,7 +1109,7 @@ class Twig {
 
    /**
    * Returns ancestors (parent, grandparent, etc.)  of the current element
-   * @param {ElementCondition} [condition] - Optional condition
+   * @param {ElementCondition} condition - Optional condition
    * @returns {Twig[]} - Array of ancestors or empty array 
    */
    ancestor = function (condition) {
@@ -1107,7 +1127,7 @@ class Twig {
 
    /**
    * Returns ancestors (parent, grandparent, etc.)  of the current element and the current element itself
-   * @param {ElementCondition} [condition] - Optional condition
+   * @param {ElementCondition} condition - Optional condition
    * @returns {Twig[]} - Array of ancestors or empty array 
    */
    ancestorOrSelf = function (condition) {
@@ -1125,7 +1145,7 @@ class Twig {
 
    /**
    * Returns all sibling element of the current element
-   * @param {ElementCondition} [condition] - Optional condition
+   * @param {ElementCondition} condition - Optional condition
    * @returns {Twig[]} - Array of sibling or empty array 
    */
    sibling = function (condition) {
@@ -1138,7 +1158,7 @@ class Twig {
 
    /**
    * Returns all sibling element of the current element and the current element itself
-   * @param {ElementCondition} [condition] - Optional condition
+   * @param {ElementCondition} condition - Optional condition
    * @returns {Twig[]} - Array of sibling or empty array 
    */
    siblingOrSelf = function (condition) {
@@ -1151,7 +1171,7 @@ class Twig {
 
    /**
    * Returns all following sibling element of the current element
-   * @param {ElementCondition} [condition] - Optional condition
+   * @param {ElementCondition} condition - Optional condition
    * @returns {Twig[]} - Array of sibling or empty array 
    */
    followingSibling = function (condition) {
@@ -1164,7 +1184,7 @@ class Twig {
 
    /**
    * Returns all preceding sibling element of the current element
-   * @param {ElementCondition} [condition] - Optional condition
+   * @param {ElementCondition} condition - Optional condition
    * @returns {Twig[]} - Array of sibling or empty array 
    */
    precedingSibling = function (condition) {
@@ -1177,7 +1197,7 @@ class Twig {
 
    /**
    * Returns next sibling element of the current element
-   * @param {ElementCondition} [condition] - Optional condition
+   * @param {ElementCondition} condition - Optional condition
    * @returns {?Twig} - The next sibling or `null`
    */
    nextSibling = function (condition) {
@@ -1192,7 +1212,7 @@ class Twig {
 
    /**
    * Returns previous sibling element of the current element
-   * @param {ElementCondition} [condition] - Optional condition
+   * @param {ElementCondition} condition - Optional condition
    * @returns {?Twig} - The previous sibling or `null`
    */
    prevSibling = function (condition) {
@@ -1225,9 +1245,9 @@ class Twig {
    /**
    * Add a new element in the current element
    * @param {string} name - The tag name
-   * @param {?string} [text] - Text of the element
-   * @param {?object} [attributes] - Element attributes
-   * @param {name|number} [position] - Position name 'first', 'last' or the position in the `children`
+   * @param {?string} text - Text of the element
+   * @param {?object} attributes - Element attributes
+   * @param {name|number} position - Position name 'first', 'last' or the position in the `children`
    * @returns {Twig} - The appended element
    */
    addElement = function (parser, name, text, attributes, position) {