xml-sax-ts 0.2.0 → 0.4.0

package/README.md

@@ -82,6 +82,31 @@ const obj = builder.getResult();
 // { item: ["1", "2"] }
 ```
 
+### Object to XML
+
+```ts
+import { objectToXml } from "xml-sax-ts";
+
+const xml = objectToXml({
+  root: {
+    "@_id": "1",
+    item: ["1", "2"],
+  }
+});
+
+// <root id="1"><item>1</item><item>2</item></root>
+```
+
+```ts
+import { buildObject, objectToXml, parseXmlString } from "xml-sax-ts";
+
+const root = parseXmlString("<root id='1'><item>1</item></root>");
+const obj = buildObject(root);
+const xml = objectToXml(obj, { rootName: "root" });
+
+// <root id="1"><item>1</item></root>
+```
+
 ### Serialize to XML
 
 ```ts
@@ -102,6 +127,120 @@ const xml = serializeXml(
 // </root>
 ```
 
+## Benchmarking
+
+Run the reproducible benchmark harness:
+
+```bash
+npm run bench
+```
+
+Quick run (fewer rounds):
+
+```bash
+npm run bench:quick
+```
+
+The benchmark now runs multiple rounds and reports median/mean/stddev for better comparability.
+
+- `xml-sax-ts:sax` scenarios measure streaming event parsing
+- `xml-sax-ts:sax` scenarios include explicit `xmlns=true/false` modes
+- `xml-sax-ts:sax ... no-position` shows upper-bound throughput with `trackPosition: false`
+- `comparable:*` scenarios run minimal equivalent feature sets for fair `xml-sax-ts` vs `saxes` comparison
+- `xml-sax-ts:tree` scenario measures full tree parsing (`parseXmlString`)
+- `sax` and `saxes` scenarios provide common SAX parser comparisons
+- `fast-xml-parser` scenarios measure object parsing on the same input corpus
+
+`fast-xml-parser`, `sax`, and `saxes` are included as dev dependencies so comparison is available out of the box.
+
+Example output includes a direct ratio line:
+
+`Comparable parse ratio (xml-sax-ts:sax vs fast-xml-parser:object): ...x`
+
+Note: SAX event parsing and object materialization are not identical workloads. Use the tree scenario for a closer semantic comparison.
+
+### Benchmark Methodology
+
+- Benchmark command: `npm run bench`
+- Runtime: Node `v24.7.0`
+- Benchmark config defaults: `BENCH_ROUNDS=5`, `BENCH_MIN_MS=1200`, `BENCH_WARMUP=10`
+- Corpus: repeated fixture corpus (`basic.xml`, `mixed.xml`, `namespaces.xml`) plus an entity-heavy synthetic case
+- Output metric: median ops/s across rounds (with mean and stddev also shown)
+
+### Benchmark Environment
+
+- Published sample run device: MacBook Pro M4
+- Memory: 48 GB RAM
+- CPU: 14-core CPU
+- GPU: 20-core GPU
+
+GPU is not used by these Node.js parser benchmarks, but listed for full machine disclosure.
+
+Latest sample (`npm run bench` defaults, Node `v24.7.0`):
+
+| Scenario | Median ops/s |
+| --- | ---: |
+| `xml-sax-ts:sax single-feed xmlns=true` | 15,155.48 |
+| `xml-sax-ts:sax single-feed xmlns=false` | 21,178.68 |
+| `xml-sax-ts:sax single-feed xmlns=false no-position` | 22,230.83 |
+| `sax:single-feed xmlns=false` | 8,357.12 |
+| `saxes:single-feed xmlns=false` | 23,296.03 |
+| `xml-sax-ts:tree parseXmlString` | 8,833.38 |
+| `fast-xml-parser:object parse` | 6,128.40 |
+
+Comparable minimal feature scenarios (fair `saxes` parity check):
+
+| Scenario | Median ops/s |
+| --- | ---: |
+| `comparable:xml-sax-ts single-feed xmlns=false position=false` | 22,637.22 |
+| `comparable:saxes single-feed xmlns=false position=false` | 23,305.98 |
+| `comparable:xml-sax-ts single-feed xmlns=true position=false` | 16,468.14 |
+| `comparable:saxes single-feed xmlns=true position=false` | 11,868.48 |
+
+- `xml-sax-ts:sax (xmlns=false)` vs `sax (xmlns=false)`: `2.534x`
+- `xml-sax-ts:sax (xmlns=true)` vs `sax (xmlns=true)`: `2.989x`
+- `xml-sax-ts:sax (xmlns=false)` vs `saxes (xmlns=false)`: `0.909x`
+- `comparable minimal (xmlns=false, xml-sax-ts vs saxes)`: `0.971x`
+- `comparable minimal (xmlns=true, xml-sax-ts vs saxes)`: `1.388x`
+- `xml-sax-ts:tree` vs `fast-xml-parser:object`: `1.441x`
+
+Benchmark visualization (same sample run):
+
+```mermaid
+xychart-beta
+  title "SAX Throughput (xmlns=false)"
+  x-axis ["xml-sax-ts", "xml-sax-ts no-position", "sax", "saxes"]
+  y-axis "ops/s" 0 --> 24000
+  bar [21178.68, 22230.83, 8357.12, 23296.03]
+```
+
+```mermaid
+xychart-beta
+  title "Object/Tree Throughput"
+  x-axis ["xml-sax-ts tree", "fast-xml-parser object"]
+  y-axis "ops/s" 0 --> 9000
+  bar [8833.38, 6128.40]
+```
+
+```mermaid
+xychart-beta
+  title "Comparable Minimal (position=false)"
+  x-axis ["xml-sax-ts xmlns=false", "saxes xmlns=false", "xml-sax-ts xmlns=true", "saxes xmlns=true"]
+  y-axis "ops/s" 0 --> 24000
+  bar [22637.22, 23305.98, 16468.14, 11868.48]
+```
+
+Legend: `xml-sax-ts` bars are the first bars in each chart.
+
+Best fair-comparison read:
+
+- Use `comparable:*` scenarios for `xml-sax-ts` vs `saxes` parity checks.
+- `xml-sax-ts ... no-position` is useful for peak throughput, but not a default-to-default comparison.
+
+These values are machine-dependent; rerun on your hardware for release-quality numbers.
+
+Current status for this environment: comparable runs show `xml-sax-ts` at `0.971x` of `saxes` on `xmlns=false` and `1.388x` on `xmlns=true`.
+
 ## API
 
 ### `XmlSaxParser`
@@ -122,6 +261,8 @@ new XmlSaxParser(options?: ParserOptions)
 | `xmlns`                       | `boolean`  | `true`  | Enable namespace resolution                    |
 | `includeNamespaceAttributes`  | `boolean`  | `false` | Include `xmlns:*` attributes in tag output     |
 | `allowDoctype`                | `boolean`  | `true`  | Allow `<!DOCTYPE …>` declarations              |
+| `coalesceText`                | `boolean`  | `false` | Merge adjacent text callbacks into one event   |
+| `trackPosition`               | `boolean`  | `true`  | Track line/column; disable for faster parsing  |
 | `onOpenTag`                   | `function` | —       | Called for each opening / self-closing tag     |
 | `onCloseTag`                  | `function` | —       | Called for each closing tag                    |
 | `onText`                      | `function` | —       | Called for text nodes                          |
@@ -131,6 +272,16 @@ new XmlSaxParser(options?: ParserOptions)
 | `onDoctype`                   | `function` | —       | Called for DOCTYPE declarations                |
 | `onError`                     | `function` | —       | Called on parse errors                         |
 
+By default (`coalesceText: false`), streaming input can produce multiple consecutive `onText` callbacks that are logically adjacent. Enable `coalesceText: true` to receive one merged text callback per structural boundary.
+
+`trackPosition` controls line/column tracking for parser errors. When set to `false`, parsing is faster and `XmlSaxError` still reports `offset`, while `line` and `column` are set to `0`.
+
+Event payload note (breaking change): with `xmlns: false`, parser events now emit plain-mode tag shapes aligned with `saxes` performance semantics.
+
+- `onOpenTag(tag).attributes` values are strings (not `XmlAttribute` objects)
+- `onOpenTag(tag)` and `onCloseTag(tag)` omit `prefix`, `local`, and `uri`
+- With `xmlns: true`, full namespace metadata remains present
+
 ### `parseXmlString(xml, options?)`
 
 Convenience function that parses a complete XML string into an `XmlNode` tree using `XmlSaxParser` + `TreeBuilder` internally.
@@ -157,6 +308,24 @@ Streaming builder that produces the same object shape as `buildObject` without b
 | `arrayElements`    | `Set\<string\> \| (name: string, path: string[]) => boolean` | —         | Force specific elements to always be arrays    |
 | `coalesceText`     | `boolean`                                                    | `true`    | Merge adjacent text nodes into a single string |
 
+### `buildXmlNode(obj, options?)`
+
+Converts a plain object into an `XmlNode` tree using the same attribute/text conventions as `buildObject`.
+
+### `objectToXml(obj, options?)`
+
+Builds an `XmlNode` with `buildXmlNode` and serializes it with `serializeXml`.
+
+#### `XmlBuilderOptions`
+
+| Option             | Type                                                         | Default   | Description                                    |
+| ------------------ | ------------------------------------------------------------ | --------- | ---------------------------------------------- |
+| `attributePrefix`  | `string`                                                     | `"@_"`    | Prefix for attribute keys                      |
+| `textKey`          | `string`                                                     | `"#text"` | Key used for text nodes                        |
+| `stripNamespaces`  | `boolean`                                                    | `false`   | Strip namespace prefixes from names            |
+| `arrayElements`    | `Set\<string\> \| (name: string, path: string[]) => boolean` | —         | Force specific elements to always be arrays    |
+| `rootName`         | `string`                                                     | —         | Root element name when object has multiple keys|
+
 ### `serializeXml(node, options?)`
 
 Serializes an `XmlNode` back to an XML string.
@@ -176,7 +345,7 @@ Custom error class thrown on parse errors. Includes `offset`, `line`, and `colum
 
 ### Exported types
 
-`OpenTag` · `CloseTag` · `XmlAttribute` · `ProcessingInstruction` · `Doctype` · `XmlNode` · `XmlChild` · `XmlPosition` · `ParserOptions` · `SerializeOptions` · `ObjectBuilderOptions` · `ArrayElementSelector` · `XmlObjectMap` · `XmlObjectValue`
+`OpenTag` · `CloseTag` · `XmlAttribute` · `ProcessingInstruction` · `Doctype` · `XmlNode` · `XmlChild` · `XmlPosition` · `ParserOptions` · `SerializeOptions` · `ObjectBuilderOptions` · `ArrayElementSelector` · `XmlObjectMap` · `XmlObjectValue` · `XmlBuilderOptions` · `XmlInputObject` · `XmlInputValue` · `ObjectToXmlOptions`
 
 ## Features