@nodable/node-tree-builder 1.0.0

package/README.md

@@ -0,0 +1,208 @@
+# Node Tree Output Builder
+
+Produces a sequential node tree where each element has three fixed properties — `tagname`, `child`, and `attributes` — plus an optional `text` property for leaf nodes.
+
+## Node structure
+
+```
+{
+  tagname: string,      // element name
+  child: array,         // ordered child nodes (always present, empty for leaf nodes)
+  attributes: object,   // always present; populated when skip.attributes is false
+  text?: any            // only present on leaf nodes (no child elements)
+}
+```
+
+### Leaf node (text only, no child elements)
+
+```js
+{ tagname: "span", child: [], attributes: {}, text: "Hello" }
+```
+
+### Empty tag (no text, no children)
+
+```js
+{ tagname: "br", child: [], attributes: {} }
+```
+
+### Tag with child elements
+
+```js
+{ tagname: "div", child: [ /* child nodes */ ], attributes: {} }
+```
+
+### Mixed content (text interleaved with child elements)
+
+Inline text runs appear as `{ ":text": value }` entries inside the `child` array. The parent node has no `text` property in this case.
+
+Input:
+```xml
+<p>Hello <b>world</b>!</p>
+```
+
+Output:
+```js
+{
+  tagname: "p",
+  child: [
+    { ":text": "Hello " },
+    { tagname: "b", child: [], attributes: {}, text: "world" },
+    { ":text": "!" }
+  ],
+  attributes: {}
+}
+```
+
+#### textInChild
+
+However, if `textInChild` is set to `true` then text is always inserted in child.
+
+
+Input:
+```xml
+<p>Hello <b>world</b>!</p>
+```
+
+Output:
+```js
+{
+  tagname: "p",
+  child: [
+    { ":text": "Hello " },
+    { tagname: "b", child: [
+      { ":text": "world" }
+      ], attributes: {}},
+    { ":text": "!" }
+  ],
+  attributes: {}
+}
+```
+
+
+## Basic example
+
+Input:
+```xml
+<root>
+  <child>hello</child>
+  <child>world</child>
+</root>
+```
+
+Output:
+```js
+{
+  tagname: "root",
+  child: [
+    { tagname: "child", child: [], attributes: {}, text: "hello" },
+    { tagname: "child", child: [], attributes: {}, text: "world" }
+  ],
+  attributes: {}
+}
+```
+
+The fixed structure lets you traverse the tree without defensive property checks.
+
+## Install
+
+```bash
+npm install @nodable/node-tree-builder
+```
+
+## Usage
+
+```js
+import XMLParser from "@nodable/flexible-xml-parser";
+import NodeTreeBuilderFactory from "@nodable/node-tree-builder";
+
+const parser = new XMLParser({
+  OutputBuilder: new NodeTreeBuilderFactory(builderOptions),
+  ...parserOptions,
+});
+
+const result = parser.parse(xmlString);
+```
+
+## Options
+
+### `attributes.groupBy` (default: `"attributes"`)
+
+The property name under which all attributes are collected. The property is **always** present on every node, even when empty.
+
+```js
+new NodeTreeBuilderFactory({
+  attributes: { groupBy: "attributes" }  // default
+})
+```
+
+To use a custom key:
+
+```js
+new NodeTreeBuilderFactory({
+  attributes: { groupBy: ":@" }
+})
+```
+
+### `nameFor.text` (default: `"#text"`)
+
+The key used for inline text entries inside `child` when a node has mixed content.
+
+```js
+new NodeTreeBuilderFactory({
+  nameFor: { text: ":text" }
+})
+```
+
+### `nameFor.comment`
+
+When skip.comment is false, this property is used to name the comment nodes.
+
+
+### `nameFor.cdata` (default: `""`)
+
+input: 
+```xml
+<root><code><![CDATA[data]]></code></root>
+```
+
+```js
+const builderConfig = { nameFor: { cdata: "##cdata" } }
+const parserConfig =  { skip: { cdata: false } }
+
+const parser = new XMLParser({
+  OutputBuilder: new NodeTreeBuilderFactory(builderConfig),
+  ...parserConfig,
+});
+
+const result = parser.parse(xmlString);
+```
+
+Output
+```js
+ {
+        "tagname": "root",
+        "child": [
+          {
+            "tagname": "code",
+            "child": [
+              {
+                "tagname": "##cdata",
+                "child": [],
+                "attributes": {},
+                "text": "data"
+              }
+            ],
+            "attributes": {}
+          }
+        ],
+        "attributes": {}
+      }
+```
+
+### `skip.attributes` (default: `true`)
+
+When `true` (default), all attributes are ignored and every node's `attributes` property is `{}`. Set to `false` to populate attributes.
+
+### Value parsers
+
+By default the parser chain `["entity", "boolean", "number"]` is applied to text content, converting strings like `"42"` to `42` and `"true"` to `true`. Override with `tags.valueParsers`.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@nodable/node-tree-builder",
+  "version": "1.0.0",
+  "description": "Node tree JS Object Sequential builder for flexible-xml-parser",
+  "main": "src/index.js",
+  "types": "./src/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "flexible-xml-parser",
+    "nodable",
+    "xml"
+  ],
+  "author": "Amit Gupta (https://solothought.com)",
+  "license": "MIT",
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nodable/base-output-builder": "^1.0.2",
+    "path-expression-matcher": "^1.4.0"
+  },
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/nodable"
+    }
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nodable/flexible-output-builder.git"
+  }
+}

package/src/NodeTreeBuilder.js

@@ -0,0 +1,177 @@
+//OrderedOutputBuilder
+
+import { buildOptions } from './ParserOptionsBuilder.js';
+import { BaseOutputBuilder, BaseOutputBuilderFactory, commonValueParsers, ElementType } from '@nodable/base-output-builder';
+
+const rootName = '!js_arr';
+
+export default class NodeTreeBuilderFactory extends BaseOutputBuilderFactory {
+  constructor(options) {
+    super()
+    this.options = buildOptions(options);
+    // this.commonValParsers = commonValueParsers();
+  }
+
+  // registerValueParser(name, parserInstance) {
+  //   this.commonValParsers[name] = parserInstance;
+  // }
+
+  getInstance(parserOptions, readonlyMatcher) {
+    const valParsers = { ...this.commonValParsers };
+    return new NodeTreeBuilder(parserOptions, this.options, valParsers, readonlyMatcher);
+  }
+}
+
+export class NodeTreeBuilder extends BaseOutputBuilder {
+
+  constructor(parserOptions, builderOptions, registeredValParsers, readonlyMatcher) {
+    super(readonlyMatcher);
+    this.tagsStack = [];
+    this.parserOptions = parserOptions;
+
+    this.options = {
+      ...parserOptions,
+      ...builderOptions,
+      skip: { ...parserOptions.skip, ...builderOptions.skip },
+      nameFor: { ...parserOptions.nameFor, ...builderOptions.nameFor },
+      tags: { ...parserOptions.tags, ...builderOptions.tags },
+      attributes: { ...parserOptions.attributes, ...builderOptions.attributes },
+    };
+
+    this.registeredValParsers = registeredValParsers;
+
+    this.root = new Node(rootName, this.options);
+    this.currentNode = this.root;
+    this.attributes = {};
+    this._pendingStopNode = false;
+  }
+
+  addElement(tag) {
+    // If the current node has text set (text arrived before any child element),
+    // retroactively migrate it into the child array as an inline text entry
+    // now that we know this is mixed content.
+    if (this.currentNode.text !== undefined) {
+      this.currentNode.child.unshift({
+        [this.options.nameFor.text]: this.currentNode.text
+      });
+      delete this.currentNode.text;
+    }
+
+    this.tagsStack.push(this.currentNode);
+    const node = new Node(tag.name, this.options);
+    // Attach any pending attributes onto the new node
+    if (this.attributes && Object.keys(this.attributes).length > 0) {
+      node[this.options.attributes.groupBy] = { ...this.attributes };
+    }
+    this.attributes = {};
+    this.currentNode = node;
+  }
+
+  /**
+   * Called when a stop node is fully collected, before `addValue`.
+   *
+   * @param {TagDetail}       tagDetail  - name, line, col, index of the stop node
+   * @param {string}          rawContent - raw unparsed content between the tags
+   */
+  onStopNode(tagDetail, rawContent) {
+    this._pendingStopNode = true;
+    if (typeof this.options.onStopNode === 'function') {
+      this.options.onStopNode(tagDetail, rawContent, this.matcher);
+    }
+  }
+
+  closeElement() {
+    const node = this.currentNode;
+    this.currentNode = this.tagsStack.pop();
+
+    this._pendingStopNode = false;
+
+    if (this.options.onClose !== undefined) {
+      const resultTag = this.options.onClose(node, this.matcher);
+      if (resultTag) return;
+    }
+
+    this.currentNode.child.push(node);
+  }
+
+  _addChild(node) {
+    // this.currentNode.child.push({ [key]: val });
+    this.currentNode.child.push(node);
+  }
+
+  addValue(text) {
+    const tagName = this.currentNode?.elementname;
+    // Check whether there are already element children (mixed content scenario)
+    const hasElementChildren = this.currentNode?.child?.some(c => c.elementname !== undefined);
+
+    const context = {
+      elementName: tagName,
+      elementValue: text,
+      elementType: ElementType.ELEMENT,
+      matcher: this.matcher,
+      isLeafNode: !hasElementChildren,
+    };
+
+    const parsedValue = this.parseValue(text, this.options.tags.valueParsers, context);
+
+    if (hasElementChildren || this.options.textInChild) {
+      // Mixed content: text alongside child elements — store as inline text child
+      this.currentNode.child.push({
+        [this.options.nameFor.text]: parsedValue
+      });
+    } else {
+      // Pure text (leaf node or text before any child elements):
+      // set directly on the node as `text` property
+      this.currentNode.text = parsedValue;
+    }
+  }
+
+  addInstruction(name) {
+    const node = new Node(name, this.options);
+    if (!isEmpty(this.attributes)) {
+      node[this.options.attributes.groupBy] = this.attributes;
+    }
+    // this.currentNode.child.push(node);
+    this._addChild(node);
+    this.attributes = {};
+  }
+
+  addComment(text) {
+    if (this.options.skip.comment) return;
+    if (this.options.nameFor.comment) {
+      const node = new Node(this.options.nameFor.comment, this.options);
+      node.text = text;
+      this._addChild(node);
+    }
+  }
+
+  addLiteral(text) {
+    if (this.options.skip.cdata) return;
+    if (this.options.nameFor.cdata) {
+      const node = new Node(this.options.nameFor.cdata, this.options);
+      node.text = text;
+      this._addChild(node);
+    } else {
+      this.addValue(text || "");
+    }
+  }
+
+  getOutput() {
+    const children = this.root.child;
+    if (children.length === 1) return children[0];
+    return children;
+  }
+}
+
+class Node {
+  constructor(elementname, options) {
+    this.elementname = elementname;
+    this.child = [];
+    const groupBy = options?.attributes?.groupBy ?? 'attributes';
+    this[groupBy] = {};
+  }
+}
+
+function isEmpty(obj) {
+  return Object.keys(obj).length === 0;
+}

package/src/ParserOptionsBuilder.js

@@ -0,0 +1,78 @@
+const defaultOptions = {
+  nameFor: {
+    text: "#text",
+    //comment: undefined,
+    //cdata: undefined,
+  },
+  skip: {
+    // declaration: false,
+    // pi: false,
+    // attributes: true,
+    // cdata: false,
+    // comment: false,
+    // nsPrefix: false,
+    // tags: false,
+  },
+  tags: {
+    valueParsers: [],
+    // stopNodes: [],
+  },
+  attributes: {
+    prefix: "@_",
+    suffix: "",
+    groupBy: "attributes",
+    valueParsers: [],
+  },
+  textInChild: false,
+};
+
+// Default chains: replaceEntities first (expand references), then type coercion.
+const defaultTagParsers = ["entity", "boolean", "number"];
+const defaultAttrParsers = ["entity", "number", "boolean"];
+
+export function buildOptions(options) {
+  const finalOptions = deepClone(defaultOptions);
+
+  if (!options || options.tags?.valueParsers === undefined) {
+    finalOptions.tags.valueParsers = [...defaultTagParsers];
+  }
+  if (!options || options.attributes?.valueParsers === undefined) {
+    finalOptions.attributes.valueParsers = [...defaultAttrParsers];
+  }
+
+  if (options) {
+    copyProperties(finalOptions, options);
+  }
+
+  return finalOptions;
+}
+
+function deepClone(obj) {
+  if (obj === null || typeof obj !== 'object') return obj;
+  if (Array.isArray(obj)) return obj.map(deepClone);
+  const clone = {};
+  for (const key of Object.keys(obj)) {
+    clone[key] = deepClone(obj[key]);
+  }
+  return clone;
+}
+
+function copyProperties(target, source) {
+  for (const key of Object.keys(source)) {
+    // Guard against prototype pollution via option keys
+    if (key === '__proto__' || key === 'constructor' || key === 'prototype') continue;
+
+    if (typeof source[key] === 'function') {
+      target[key] = source[key];
+    } else if (Array.isArray(source[key])) {
+      target[key] = source[key];
+    } else if (typeof source[key] === 'object' && source[key] !== null) {
+      if (typeof target[key] !== 'object' || target[key] === null) {
+        target[key] = {};
+      }
+      copyProperties(target[key], source[key]);
+    } else {
+      target[key] = source[key];
+    }
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,160 @@
+export interface SkipOptions {
+  /** Skip XML declaration `<?xml ... ?>` from output. Default: false */
+  declaration?: boolean;
+  /** Skip processing instructions (other than declaration) from output. Default: false */
+  pi?: boolean;
+  /**
+   * Skip all attributes from output. When true (default), the `attributes`
+   * property on every node is an empty object `{}`.
+   * Set to false to populate attributes.
+   * Default: true
+   */
+  attributes?: boolean;
+  /** Exclude CDATA sections entirely from output. Default: false */
+  cdata?: boolean;
+  /** Exclude comments entirely from output. Default: false */
+  comment?: boolean;
+  /**
+   * Strip namespace prefixes from tag and attribute names.
+   * E.g. `ns:tag` → `tag`, `xmlns:*` attributes are dropped.
+   * Default: false
+   */
+  nsPrefix?: boolean;
+  /** (future) Tag-level filtering — not yet implemented. Default: false */
+  tags?: boolean;
+}
+
+export interface NameForOptions {
+  /**
+   * Property name for inline text nodes in mixed content
+   * (i.e. text that appears alongside child elements in the same parent).
+   * These appear as `{ [text]: value }` entries in the `child` array.
+   * Default: '#text'
+   */
+  text?: string;
+  /**
+   * Property name for CDATA sections.
+   * Empty string (default) merges CDATA content into the node's `text` value.
+   */
+  cdata?: string;
+  /**
+   * Property name for XML comments.
+   * Empty string (default) omits comments from output.
+   * Set e.g. '#comment' to capture them.
+   */
+  comment?: string;
+}
+
+export interface AttributeOptions {
+  /** Allow boolean (valueless) attributes — treated as `true`. Default: false */
+  booleanType?: boolean;
+  /**
+   * Property name under which all attributes are grouped on each node.
+   * The `attributes` property is always present (empty `{}` when no attributes
+   * or when `skip.attributes` is true).
+   * Default: 'attributes'
+   */
+  groupBy?: string;
+  /** Prefix prepended to attribute names in output. Default: '@_' */
+  prefix?: string;
+  /** Suffix appended to attribute names in output. Default: '' */
+  suffix?: string;
+  /**
+   * Value parser chain for attribute values.
+   * Built-in names: 'entity', 'number', 'boolean', 'trim', 'currency'.
+   * Default: ['entity', 'number', 'boolean']
+   */
+  valueParsers?: Array<string | ValueParser>;
+}
+
+export interface TagOptions {
+  /**
+   * Value parser chain for tag text content.
+   * Built-in names: 'entity', 'boolean', 'number', 'trim', 'currency'.
+   * Default: ['entity', 'boolean', 'number']
+   * Add 'trim' to strip leading/trailing whitespace (not done by default).
+   */
+  valueParsers?: Array<string | ValueParser>;
+}
+
+export interface FactoryOptions {
+  /** Fine-grained control over which node types appear in output */
+  skip?: SkipOptions;
+
+  /** Property names used for special nodes in output */
+  nameFor?: NameForOptions;
+
+  /** Attribute parsing and representation options */
+  attributes?: AttributeOptions;
+
+  /** Tag parsing options including stop nodes and value parser chain */
+  tags?: TagOptions;
+}
+
+/**
+ * A parsed XML node as produced by NodeTreeBuilder.
+ *
+ * - `tagname`    — element name
+ * - `child`      — ordered array of child nodes; empty for leaf nodes
+ * - `attributes` — always present; populated when `skip.attributes` is false
+ * - `text`       — only present on leaf nodes (no child elements); holds the
+ *                  parsed text value (may be string, number, or boolean
+ *                  depending on the active value-parser chain)
+ *
+ * In mixed content (text interleaved with child elements), inline text runs
+ * appear in `child` as `{ [nameFor.inlineText]: value }` objects (default
+ * key is `":text"`). The parent node has no `text` property in that case.
+ */
+export interface XmlNode {
+  tagname: string;
+  child: Array<XmlNode | Record<string, any>>;
+  attributes: Record<string, any>;
+  text?: string | number | boolean;
+  [key: string]: any;
+}
+
+export interface NodeTreeBuilderInstance {
+  addElement(tag: { name: string }, matcher: any): void;
+  closeElement(matcher: any): void;
+  addValue(text: string, matcher: any): void;
+  addAttribute(name: string, value: any): void;
+  addComment(text: string): void;
+  addLiteral(text: string): void;
+  addDeclaration(): void;
+  addInstruction(name: string): void;
+  /**
+   * Called by the XML parser after the DOCTYPE block is read.
+   * Implementations forward entities to any registered value parser
+   * that implements addInputEntities().
+   */
+  addInputEntities(entities: object): void;
+  getOutput(): XmlNode | XmlNode[];
+  registeredValParsers: Record<string, ValueParser>;
+  /**
+   * Optional hook called by the parser when a stop node is fully collected.
+   * Delegates to the `options.onStopNode` callback when supplied.
+   */
+  onStopNode?(
+    tagDetail: { name: string; line: number; col: number; index: number },
+    rawContent: string,
+    matcher: any,
+  ): void;
+}
+
+/**
+ * A value parser transforms a value in the parsing chain.
+ * Receives the current value and an optional context object.
+ */
+export interface ValueParser {
+  /**
+   * @param val     Current value (string initially; may already be typed if earlier parsers ran)
+   * @param context { tagName, isAttribute, attrName? }
+   */
+  parse(val: any, context?: { tagName: string; isAttribute: boolean; attrName?: string }): any;
+}
+
+export class NodeTreeBuilderFactory {
+  constructor(options?: Partial<FactoryOptions>);
+  getInstance(factoryOptions: FactoryOptions): NodeTreeBuilderInstance;
+  registerValueParser(name: string, parser: ValueParser): void;
+}

package/src/index.js

@@ -0,0 +1 @@
+export { default as NodeTreeBuilderFactory, NodeTreeBuilder } from './NodeTreeBuilder.js';