Use @nodable/entities v2.1.0

Author: amitguptagwl

CHANGELOG.md

@@ -2,6 +2,21 @@
 
 Note: Due to some last quick changes on v4, detail of v4.5.3 & v4.5.4 are not updated here. v4.5.4x is the last tag of v4 in github repository. I'm extremely sorry for the confusion
 
+**5.7.0**
+- Use `@nodable/entities` v2.1.0
+  - breaking changes
+    - single entity scan. You're not allowed to user entity value to form another entity name.
+    - you cant add numeric external entity
+    - entity error message when expantion limit is crossed might change
+  - typings are updated for new options related to process entity
+  - please follow documentation of `@nodable/entities` for more detail.
+  - performance
+    - if processEntities is false, then there should not be impact on performance.
+    - if processEntities is true, but you dont pass entity decoder separately then performance may degrade by approx 8-10%
+    - if processEntities is true, and you pass entity decoder separately
+      - if no entity then performance should be same as before
+      - if there are entities then performance should be increased
+
 **5.6.0 / 2026-04-15**
 - fix: entity replacement for numeric entities
 - use @nodable/entities to replace entities

docs/v4, v5/2.XMLparseOptions.md

@@ -351,6 +351,34 @@ Output
 ## htmlEntities
 FXP by default parse XML entities if `processEntities: true`. You can set `htmlEntities` to parse HTML entities. Check [entities](./5.Entities.md) section for more information.
 
+## entityDecoder
+
+`entityDecoder` option is supported v5.7.0 onward. It allows you to set your own entity decoder which supports following methods.
+
+```
+type EntityDecoderOptions = {
+  setExternalEntities: (entities: Record<string, string>) => void;
+  addInputEntities: (entities: Record<string, string>) => void;
+  reset: () => void;
+  decode: (text: string) => string;
+  setXmlVersion: (version: string) => void;
+}
+```
+
+We're not explicitely checking the type and required methods but parser may throw error if the provided object doesn't have the required methods.
+
+If XML document has version attribute in xml declaration then it will be passed to `setXmlVersion` method of the decoder to handle NCR gradefully.
+
+When `processEntities` is set to `false` then `entityDecoder` will not be used. But if 'true' and `entityDecoder` is not provided then default entity decoder (`@nodable/entities`) will be used.
+
+When `entityDecoder` is provided then following options which are set ot parser directly will be ignored. User is expected them to set them in decoder's config.
+- htmlEntities
+- maxTotalExpansions
+- maxExpandedLength
+
+
+
+
 ## ignoreAttributes
 
 By default, `ignoreAttributes` is set to `true`. This means that attributes are ignored by the parser. If you set any configuration related to attributes without setting `ignoreAttributes: false`, it will not have any effect.

docs/v4, v5/5.Entities.md

@@ -140,8 +140,6 @@ Output:
 </note>
 ```
 
-## Side Effects
-
 FXP silently ignores entities with `&` in their values for security. However, be aware of how multiple entities interact:
 
 ```xml
@@ -190,27 +188,7 @@ While FXP blocks many entity-based attacks through its security limits and by re
 
 ## HTML Entities
 
-Following HTML entities are supported when `htmlEntities: true`:
-
-| Result | Description                        | Entity Name | Entity Number |
-| :----- | :--------------------------------- | :---------- | :------------ |
-|        | non-breaking space                 | `&nbsp;`    | `&#160;`      |        
-| <      | less than                          | `&lt;`      | `&#60;`       |        
-| >      | greater than                       | `&gt;`      | `&#62;`       |        
-| &      | ampersand                          | `&amp;`     | `&#38;`       |        
-| "      | double quotation mark              | `&quot;`    | `&#34;`       |        
-| '      | single quotation mark              | `&apos;`    | `&#39;`       |        
-| ¢      | cent                               | `&cent;`    | `&#162;`      |        
-| £      | pound                              | `&pound;`   | `&#163;`      |        
-| ¥      | yen                                | `&yen;`     | `&#165;`      |        
-| €      | euro                               | `&euro;`    | `&#8364;`     |        
-| ©      | copyright                          | `&copy;`    | `&#169;`      |        
-| ®      | registered trademark               | `&reg;`     | `&#174;`      |        
-| ₹      | Indian Rupee                       | `&inr;`     | `&#8377;`     |
-
-In addition, [numeric character references](https://html.spec.whatwg.org/multipage/syntax.html#syntax-charref) are supported - both decimal (`&#123;`) and hexadecimal (`&#x7B;`).
-
-FXP supports reading Notations and Elements from v5.2.1 onwards. However, it doesn't take any action based on these values.
+[Common HTML entities](https://github.com/nodable/val-parsers/blob/main/Entity/src/entities.js#L1152) and numeric (decimal, hex) are supported when `htmlEntities: true`:
 
 ## External Entities
 
@@ -228,4 +206,6 @@ This method also allows you to override default entities.
 
 **Note:** External entities added this way bypass DOCTYPE validation but are still subject to the same security limits when `processEntities: true`.
 
+You can't set numerical or NCR entities as external entity.
+
 [> Next: HTML Document Parsing](./6.HTMLParsing.md)

lib/fxp.d.cts

@@ -219,6 +219,14 @@ type ProcessEntitiesOptions = {
   tagFilter?: ((tagName: string, jPathOrMatcher: JPathOrMatcher) => boolean) | null;
 };
 
+type EntityDecoderOptions = {
+  setExternalEntities: (entities: Record<string, string>) => void;
+  addInputEntities: (entities: Record<string, string>) => void;
+  reset: () => void;
+  decode: (text: string) => string;
+  setXmlVersion: (version: string) => void;
+}
+
 type X2jOptions = {
   /**
    * Preserve the order of tags in resulting JS object
@@ -398,16 +406,22 @@ type X2jOptions = {
    * When `ProcessEntitiesOptions` - enables entity processing with custom configuration
    * 
    * Defaults to `true`
+   * @deprecated Use `entityDecoder` instead
    */
   processEntities?: boolean | ProcessEntitiesOptions;
 
   /**
    * Whether to process HTML entities
    * 
    * Defaults to `false`
+   * @deprecated Use `entityDecoder` instead
    */
   htmlEntities?: boolean;
 
+  /**
+   * Custom entity decoder
+   */
+  entityDecoder?: EntityDecoderOptions;
   /**
    * Whether to ignore the declaration tag from output
    * 
@@ -713,8 +727,10 @@ declare class XMLParser {
 declare class XMLValidator {
   static validate(xmlData: string, options?: validationOptions): true | ValidationError;
 }
-
-declare class XMLBuilder {
+/**
+ * @deprecated Use npm package 'fast-xml-builder' instead
+ */
+devlare class XMLBuilder {
   constructor(options?: XmlBuilderOptions);
   build(jObj: any): string;
 }
@@ -747,6 +763,7 @@ declare namespace fxp {
     MatcherView,
     JPathOrMatcher,
     JPathOrExpression,
+    EntityDecoderOptions
   }
 }
 

package-lock.json

@@ -87,9 +87,9 @@
     }
   ],
   "dependencies": {
-    "@nodable/entities": "^1.1.0",
+    "@nodable/entities": "^2.1.0",
     "fast-xml-builder": "^1.1.4",
     "path-expression-matcher": "^1.5.0",
     "strnum": "^2.2.3"
   }
-}
+}

package.json

@@ -72,7 +72,7 @@ describe("XMLParser entity expansion security", function () {
 
       expect(function () {
         parser.parse(xmlData);
-      }).toThrowError("[EntityReplacer] Entity expansion count limit exceeded: 1500 > 1000");
+      }).toThrowError("[EntityReplacer] Entity expansion count limit exceeded: 1001 > 1000");
     });
 
     it("should allow expansions within limit", function () {
@@ -109,7 +109,7 @@ describe("XMLParser entity expansion security", function () {
 
       expect(function () {
         parser.parse(xmlData);
-      }).toThrowError("[EntityReplacer] Entity expansion count limit exceeded: 1200 > 1000");
+      }).toThrowError("[EntityReplacer] Entity expansion count limit exceeded: 1001 > 1000");
     });
   });
 
@@ -132,7 +132,7 @@ describe("XMLParser entity expansion security", function () {
 
       expect(function () {
         parser.parse(xmlData);
-      }).toThrowError("[EntityReplacer] Expanded content length limit exceeded: 149250 > 100000");
+      }).toThrowError("[EntityReplacer] Expanded content length limit exceeded: 100495 > 100000");
     });
 
     it("should allow expansions within maxExpandedLength", function () {
@@ -188,7 +188,7 @@ describe("XMLParser entity expansion security", function () {
 
       expect(function () {
         parser.parse(xmlData);
-      }).toThrowError("[EntityReplacer] Entity expansion count limit exceeded: 5000 > 1000");
+      }).toThrowError("[EntityReplacer] Entity expansion count limit exceeded: 1001 > 1000");
     });
 
     it("should prevent billion laughs with maxExpandedLength", function () {
@@ -205,7 +205,7 @@ describe("XMLParser entity expansion security", function () {
 
       expect(function () {
         parser.parse(xmlData);
-      }).toThrowError("[EntityReplacer] Expanded content length limit exceeded: 199000 > 100000");
+      }).toThrowError("[EntityReplacer] Expanded content length limit exceeded: 100495 > 100000");
     });
   });
 
@@ -407,7 +407,7 @@ describe("XMLParser entity expansion security", function () {
 
       expect(function () {
         parser.parse(xmlData);
-      }).toThrowError("[EntityReplacer] Expanded content length limit exceeded: 19400 > 10000");
+      }).toThrowError("[EntityReplacer] Expanded content length limit exceeded: 10088 > 10000");
     });
   });