@nodable/sequential-builder 1.0.0

package/README.md

@@ -0,0 +1,214 @@
+# Sequential Output Builder
+
+Produces a sequential array where every element is represented as an object with the **tag name directly as a key** pointing to its children array. There is no separate `elementname` property — the structure is array-first throughout.
+
+## Output structure
+
+```
+[                          ← getOutput() always returns an array
+  {
+    [tagName]: Array,      ← tag name → children array (always present, empty for leaf/empty nodes)
+    [groupBy]?: object,    ← attributes as a sibling property (only when non-empty)
+    text?: any             ← only present on leaf nodes (no child element entries)
+  }
+]
+```
+
+### Leaf node (text only, no child elements)
+
+```js
+{ span: [], text: "Hello" }
+```
+
+### Empty tag (no text, no children)
+
+```js
+{ br: [] }
+```
+
+### Tag with child elements
+
+```js
+{ div: [ /* child entries */ ] }
+```
+
+### Tag with attributes and text
+
+```js
+{ item: [], attributes: { "@_id": 1 }, text: "hello" }
+```
+
+Attributes are a **sibling property** alongside the tag key — they are not nested inside the children array.
+
+### Mixed content (text interleaved with child elements)
+
+Inline text runs appear as `{ "#text": value }` entries inside the children array. The entry itself has no `text` property in this case.
+
+Input:
+```xml
+<p>Hello <b>world</b>!</p>
+```
+
+Output:
+```js
+[
+  {
+    p: [
+      { "#text": "Hello " },
+      { b: [], text: "world" },
+      { "#text": "!" }
+    ]
+  }
+]
+```
+
+## Basic example
+
+Input:
+```xml
+<root>
+  <child>hello</child>
+  <child>world</child>
+</root>
+```
+
+Output:
+```js
+[
+  {
+    root: [
+      { child: [], text: "hello" },
+      { child: [], text: "world" }
+    ]
+  }
+]
+```
+
+## Install
+
+```bash
+npm install @nodable/sequential-builder
+```
+
+## Usage
+
+```js
+import XMLParser from "@nodable/flexible-xml-parser";
+import {SequentialBuilderFactory} from "@nodable/sequential-builder";
+
+const parser = new XMLParser({
+  OutputBuilder: new SequentialBuilderFactory(builderOptions),
+  ...parserOptions,
+});
+
+const result = parser.parse(xmlString);
+// result is always an array
+```
+
+## Options
+
+### `attributes.groupBy` (default: `"attributes"`)
+
+The property name under which all attributes are collected as a sibling alongside the tag key. The property is **only present** when attributes exist and `skip.attributes` is false.
+
+```js
+new SequentialBuilderFactory({
+  attributes: { groupBy: "attributes" }  // default
+})
+```
+
+To use a custom key:
+
+```js
+new SequentialBuilderFactory({
+  attributes: { groupBy: ":@" }
+})
+```
+
+### `nameFor.text` (default: `"#text"`)
+
+The key used for inline text entries inside the children array when a node has mixed content (text interleaved with child elements).
+
+```js
+new SequentialBuilderFactory({
+  nameFor: { text: ":text" }
+})
+```
+
+### `nameFor.comment`
+
+When `skip.comment` is false, this property name is used for comment entries in the children array.
+
+```js
+new SequentialBuilderFactory({
+  nameFor: { comment: "#comment" }
+})
+```
+
+### `nameFor.cdata`
+
+When set, CDATA sections appear as `{ [cdata]: value }` entries in the children array. When unset (default), CDATA content is merged into the node's `text` value (same as regular text).
+
+```js
+// builder config
+const builderConfig = { nameFor: { cdata: "##cdata" } };
+// parser config
+const parserConfig  = { skip: { cdata: false } };
+
+const parser = new XMLParser({
+  OutputBuilder: new SequentialBuilderFactory(builderConfig),
+  ...parserConfig,
+});
+```
+
+Output for `<root><code><![CDATA[data]]></code></root>`:
+```js
+[
+  {
+    root: [
+      {
+        code: [
+          { "##cdata": "data" }
+        ]
+      }
+    ]
+  }
+]
+```
+
+### `textInChild` (default: `false`)
+
+When `true`, text is always stored as a `{ [nameFor.text]: value }` entry in the children array — even on pure leaf nodes that have no element children. The `text` sibling property is never set in this mode.
+
+```js
+new SequentialBuilderFactory({ textInChild: true })
+```
+
+Input:
+```xml
+<root><a>hello</a></root>
+```
+
+Default output (`textInChild: false`):
+```js
+[ { root: [ { a: [], text: "hello" } ] } ]
+```
+
+Output with `textInChild: true`:
+```js
+[ { root: [ { a: [ { "#text": "hello" } ] } ] } ]
+```
+
+### `skip.attributes` (default: `true`)
+
+When `true` (default), all attributes are ignored and no `attributes` property appears on entries. Set to `false` to populate attributes.
+
+### Value parsers
+
+By default the parser chain `["entity", "boolean", "number"]` is applied to text content, converting `"42"` → `42` and `"true"` → `true`. Override with `tags.valueParsers`.
+
+```js
+new SequentialBuilderFactory({
+  tags: { valueParsers: [] }   // keep all values as raw strings
+})
+```

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@nodable/sequential-builder",
+  "version": "1.0.0",
+  "description": "Sequential JS Array 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"
+  ],
+  "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/ParserOptionsBuilder.js

@@ -0,0 +1,78 @@
+const defaultOptions = {
+  nameFor: {
+    text: "#text",
+    // comment: "",
+    // cdata: "",
+  },
+  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/SequentialBuilder.js

@@ -0,0 +1,219 @@
+import { buildOptions } from './ParserOptionsBuilder.js';
+import { BaseOutputBuilder, BaseOutputBuilderFactory, ElementType } from '@nodable/base-output-builder';
+
+const rootName = '!sequential_root';
+
+export default class SequentialBuilderFactory extends BaseOutputBuilderFactory {
+  constructor(options) {
+    super();
+    this.options = buildOptions(options);
+  }
+
+  getInstance(parserOptions, readonlyMatcher) {
+    const valParsers = { ...this.commonValParsers };
+    return new SequentialBuilder(parserOptions, this.options, valParsers, readonlyMatcher);
+  }
+}
+
+export class SequentialBuilder 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 children array as an inline text entry
+    // now that we know this is mixed content.
+    if (this.currentNode.text !== undefined) {
+      this.currentNode.children.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;
+    }
+
+    // Build the sequential representation:
+    // { [tagName]: children, [groupBy]: attributes, text? }
+    // Tag name directly points to the children array.
+    // Attributes (when present) are a sibling property alongside the tag key.
+    const entry = { [node.tagname]: node.children };
+
+    const groupBy = this.options.attributes.groupBy;
+    if (node[groupBy] && Object.keys(node[groupBy]).length > 0) {
+      entry[groupBy] = node[groupBy];
+    }
+
+    // text is a sibling property (leaf-node case — no element children)
+    if (node.text !== undefined) {
+      entry.text = node.text;
+    }
+
+    this.currentNode.children.push(entry);
+  }
+
+  addValue(text) {
+    const tagName = this.currentNode?.tagname;
+    // Check whether there are already element children (mixed content scenario).
+    // Mixed content = children that are NOT bare text entries.
+    const hasElementChildren = this.currentNode?.children?.some(
+      c => !Object.prototype.hasOwnProperty.call(c, this.options.nameFor.text)
+    );
+
+    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.children.push({
+        [this.options.nameFor.text]: parsedValue
+      });
+    } else {
+      // Pure text (leaf node or text before any child elements):
+      // set directly on the node; promoted to sibling property in closeElement.
+      this.currentNode.text = parsedValue;
+    }
+  }
+
+  addInstruction(name) {
+    const node = new Node(name, this.options);
+    const groupBy = this.options.attributes.groupBy;
+    if (this.attributes && Object.keys(this.attributes).length > 0) {
+      node[groupBy] = { ...this.attributes };
+    }
+    const entry = { [node.tagname]: node.children };
+    if (node[groupBy] && Object.keys(node[groupBy]).length > 0) {
+      entry[groupBy] = node[groupBy];
+    }
+    this.currentNode.children.push(entry);
+    this.attributes = {};
+  }
+
+  addComment(text) {
+    if (this.options.skip.comment) return;
+    if (this.options.nameFor.comment) {
+      this.currentNode.children.push({
+        [this.options.nameFor.comment]: text
+      });
+    }
+  }
+
+  addLiteral(text) {
+    if (this.options.skip.cdata) return;
+    if (this.options.nameFor.cdata) {
+      this.currentNode.children.push({
+        [this.options.nameFor.cdata]: text
+      });
+    } else {
+      this.addValue(text || '');
+    }
+  }
+
+  getOutput() {
+    return this.root.children;
+  }
+
+  /**
+ * Called by the parser when `exitIf` returns true for the current tag.
+ * Receives a snapshot of the parser state at the moment of exit, after
+ * all open tags have been cleanly closed by the parser.
+ *
+ * Override in subclasses to record the exit position or annotate output.
+ *
+ * @param {object} exitInfo
+ * @param {object} exitInfo.tagDetail   - `{ name, line, col, index }` of the
+ *                                        tag that triggered the exit.
+ * @param {object} exitInfo.matcher     - Read-only matcher positioned at
+ *                                        that tag at the moment exitIf fired.
+ * @param {number} exitInfo.depth       - Nesting depth at exit (0 = root children).
+ */
+  onExit(exitInfo) {
+    // Base implementation: attach exit metadata to the output root so callers
+    // can tell the parse was intentionally truncated and where it stopped.
+    // Stored under __exitInfo to avoid colliding with any tag-derived key.
+    // Subclasses may override to suppress, transform, or log this information.
+    // if (this.value && typeof this.value === 'object') {
+    //   Object.defineProperty(this.value, '__exitInfo', {
+    //     value: {
+    //       tag: exitInfo.tagDetail.name,
+    //       line: exitInfo.tagDetail.line,
+    //       col: exitInfo.tagDetail.col,
+    //       index: exitInfo.tagDetail.index,
+    //       depth: exitInfo.depth,
+    //     },
+    //     enumerable: false,   // invisible to JSON.stringify and for-in
+    //     configurable: true,
+    //     writable: true,
+    //   });
+    // }
+
+    //Do nothing
+  }
+}
+
+class Node {
+  constructor(tagname, options) {
+    this.tagname = tagname;
+    this.children = [];
+    const groupBy = options?.attributes?.groupBy ?? 'attributes';
+    this[groupBy] = {};
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,170 @@
+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 entry 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 children array.
+   * Default: '#text'
+   */
+  text?: string;
+  /**
+   * Property name for CDATA sections.
+   * When set, CDATA nodes appear as `{ [cdata]: value }` entries in the children array.
+   * When unset (default), CDATA content is merged into the node's `text` value.
+   */
+  cdata?: string;
+  /**
+   * Property name for XML comments.
+   * When unset (default), comments are omitted from output.
+   * Set e.g. '#comment' to capture them as `{ '#comment': value }` entries.
+   */
+  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 entry, as a
+   * sibling alongside the tag-name key.
+   * 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']
+   */
+  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;
+
+  /**
+   * When true, text is always stored as a `{ [nameFor.text]: value }` child entry,
+   * even on pure leaf nodes (no mixed content required).
+   * Default: false — leaf text is stored as a `text` sibling property on the entry.
+   */
+  textInChild?: boolean;
+}
+
+/**
+ * A parsed XML entry as produced by SequentialBuilder.
+ *
+ * Structure:
+ *   {
+ *     [tagName]: Array<SequentialEntry>,   // tag name directly points to children array
+ *     [groupBy]?: Record<string, any>,     // attributes (sibling property; present only when non-empty)
+ *     text?: any                           // only present on leaf nodes (no child element entries)
+ *   }
+ *
+ * Leaf node (text only, no child elements):
+ *   { child: [], text: "Hello" }           — wait, the key IS the tag name:
+ *   { span: [], text: "Hello" }
+ *
+ * Empty tag:
+ *   { br: [] }
+ *
+ * Tag with child elements:
+ *   { div: [ ...childEntries ] }
+ *
+ * Tag with attributes:
+ *   { item: [], attributes: { "@_id": 1 }, text: "val" }
+ *
+ * Mixed content (text interleaved with child elements):
+ *   Inline text runs appear as `{ [nameFor.text]: value }` entries inside the array.
+ *   The entry has no `text` property in that case.
+ *
+ * The overall `getOutput()` returns an array — always — even for a single root element.
+ */
+export type SequentialEntry = Record<string, any>;
+
+export interface SequentialBuilderInstance {
+  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(): SequentialEntry[];
+  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.
+ */
+export interface ValueParser {
+  parse(val: any, context?: { tagName: string; isAttribute: boolean; attrName?: string }): any;
+}
+
+export class SequentialBuilderFactory {
+  constructor(options?: Partial<FactoryOptions>);
+  getInstance(factoryOptions: FactoryOptions): SequentialBuilderInstance;
+  registerValueParser(name: string, parser: ValueParser): void;
+}

package/src/index.js

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