@nodable/flexible-xml-parser 1.0.0

package/src/InputSource/StringSource.js

@@ -0,0 +1,225 @@
+import { ParseError, ErrorCode } from '../ParseError.js';
+
+/**
+ * StringSource — input source backed by an in-memory string.
+ *
+ * ### Memory reclamation
+ *
+ * Unlike FeedableSource, the full document is available from the start, so
+ * there is no chunk-boundary risk and rewindToMark() is a safe no-op.
+ * However, the parsed prefix of the string is still held in memory until the
+ * parse finishes. flush() reclaims that prefix by slicing the buffer and
+ * resetting startIndex to 0.
+ *
+ * The same mark/flush protocol used by FeedableSource is implemented here so
+ * all reader functions (readTagExp, readClosingTagName, readCdata, etc.) work
+ * without any source-type conditionals:
+ *
+ *   markTokenStart()  — save the current read position at the start of a token
+ *   rewindToMark()    — no-op for StringSource (full doc always present)
+ *   flush()           — drop the already-parsed prefix to free memory
+ *
+ * Auto-flush fires inside updateBufferBoundary() whenever the processed
+ * portion exceeds flushThreshold and no token checkpoint is active.
+ */
+export default class StringSource {
+  /**
+   * @param {string} str — the full XML document string
+   * @param {object} [options]
+   * @param {boolean} [options.autoFlush=true]      — enable automatic flushing
+   * @param {number}  [options.flushThreshold=1024] — flush after this many processed chars
+   */
+  constructor(str, options = {}) {
+    this.line = 1;
+    this.cols = 0;
+    this.buffer = str;
+    // Boundary pointer: data before this index has been consumed and may be freed.
+    this.startIndex = 0;
+
+    this.autoFlush = options.autoFlush !== false;
+    this.flushThreshold = options.flushThreshold ?? 1024;
+
+    // Two-level mark stack matching FeedableSource's API.
+    // _marks[0] = outer mark (parseXml loop), _marks[1] = inner mark (readers).
+    // -1 means "not set" for that level.
+    this._marks = [-1, -1];
+  }
+
+  // ─── Token-start checkpoint ───────────────────────────────────────────────
+
+  /**
+   * Save the current read position into the two-level mark stack.
+   *
+   * Mirrors FeedableSource's two-level API so all reader functions work
+   * identically regardless of source type:
+   *
+   *   level 0 (default) — outer mark, set by parseXml()'s main loop.
+   *   level 1           — inner mark, set by individual reader functions.
+   *
+   * For StringSource the distinction only matters for flush() boundary
+   * calculations — rewindToMark() is always a no-op here.
+   *
+   * @param {0|1} [level=0]
+   */
+  markTokenStart(level = 0) {
+    this._marks[level] = this.startIndex;
+  }
+
+  /**
+   * Restore startIndex to the last markTokenStart() position.
+   *
+   * StringSource always has the full document available, so a mid-token end
+   * of input cannot occur and this method is a safe no-op. It exists solely
+   * so caller code (XMLParser.feed / parseXml) can call rewindToMark()
+   * unconditionally without branching on source type.
+   */
+  rewindToMark() {
+    // No-op: the complete document is in memory; no rewind is ever needed.
+  }
+
+  /** Clear both mark slots (mirrors FeedableSource.clearMark). */
+  clearMark() {
+    this._marks[0] = -1;
+    this._marks[1] = -1;
+  }
+
+  /**
+   * Discard the already-processed prefix of the buffer to free memory.
+   *
+   * The flush origin is the minimum of all active mark positions so that any
+   * in-progress token (at either mark level) is preserved in the buffer.
+   * If no marks are active, the origin is startIndex itself.
+   */
+  flush() {
+    let origin = this.startIndex;
+    for (const m of this._marks) {
+      if (m >= 0 && m < origin) origin = m;
+    }
+    if (origin > 0) {
+      this.buffer = this.buffer.substring(origin);
+      const marksLen = this._marks.length;
+      for (let i = 0; i < marksLen; i++) {
+        if (this._marks[i] >= 0) this._marks[i] -= origin;
+      }
+      this.startIndex -= origin;
+    }
+  }
+
+  // ─── Core read interface ──────────────────────────────────────────────────
+
+  readCh() {
+    return this.buffer[this.startIndex++];
+  }
+
+  readChAt(index) {
+    return this.buffer[this.startIndex + index];
+  }
+
+  readStr(n, from) {
+    if (typeof from === 'undefined') from = this.startIndex;
+    return this.buffer.substring(from, from + n);
+  }
+
+  readUpto(stopStr) {
+    const inputLength = this.buffer.length;
+    const stopLength = stopStr.length;
+
+    for (let i = this.startIndex; i < inputLength; i++) {
+      let match = true;
+      for (let j = 0; j < stopLength; j++) {
+        if (this.buffer[i + j] !== stopStr[j]) { match = false; break; }
+      }
+      if (match) {
+        const result = this.buffer.substring(this.startIndex, i);
+        this.startIndex = i + stopLength;
+        return result;
+      }
+    }
+
+    throw new ParseError(`Unexpected end of source reading '${stopStr}'`, ErrorCode.UNEXPECTED_END);
+  }
+
+  /**
+   * Single-character variant of readUpto — faster because there is no inner
+   * match loop.  Reads until `stopChar` is found, consumes it, and returns
+   * the text before it.
+   *
+   * @param {string} stopChar  Exactly one character.
+   * @returns {string}
+   */
+  readUptoChar(stopChar) {
+    const i = this.buffer.indexOf(stopChar, this.startIndex);
+    if (i === -1) {
+      throw new ParseError(`Unexpected end of source reading '${stopChar}'`, ErrorCode.UNEXPECTED_END);
+    }
+    const result = this.buffer.substring(this.startIndex, i);
+    this.startIndex = i + 1;
+    return result;
+  }
+
+  readUptoCloseTag(stopStr) { // stopStr: "</tagname"
+    const inputLength = this.buffer.length;
+    const stopLength = stopStr.length;
+    let tagMatchStart = -1;
+    // 0: scanning, 1: tag-name matched (scanning for '>'), 2: full match
+    let state = 0;
+
+    for (let i = this.startIndex; i < inputLength; i++) {
+      if (state === 1) {
+        const c = this.buffer[i];
+        if (c === ' ' || c === '\t') continue;
+        if (c === '>') { state = 2; }
+        else { state = 0; tagMatchStart = -1; } // false match e.g. </scriptX>
+      } else {
+        // Try to match stopStr at position i
+        let matched = true;
+        for (let j = 0; j < stopLength; j++) {
+          if (this.buffer[i + j] !== stopStr[j]) { matched = false; break; }
+        }
+        if (matched) {
+          state = 1;
+          tagMatchStart = i;
+          i += stopLength - 1; // skip past matched string
+        }
+      }
+      if (state === 2) {
+        const result = this.buffer.substring(this.startIndex, tagMatchStart);
+        this.startIndex = i + 1;
+        return result;
+      }
+    }
+
+    throw new ParseError(`Unexpected end of source reading '${stopStr}'`, ErrorCode.UNEXPECTED_END);
+  }
+
+  readFromBuffer(n, updateIndex) {
+    const ch = n === 1
+      ? this.buffer[this.startIndex]
+      : this.buffer.substring(this.startIndex, this.startIndex + n);
+    if (updateIndex) this.updateBufferBoundary(n);
+    return ch;
+  }
+
+  /**
+   * Advance the read cursor by n characters.
+   *
+   * Triggers an automatic flush of already-processed data when autoFlush is
+   * enabled, the processed portion has grown past flushThreshold, and no
+   * token checkpoint is currently active (a flush while a checkpoint is live
+   * would invalidate the saved position).
+   *
+   * @param {number} [n=1]
+   */
+  updateBufferBoundary(n = 1) {
+    this.startIndex += n;
+    const anyMarkActive = this._marks[0] >= 0 || this._marks[1] >= 0;
+    if (this.autoFlush && this.startIndex >= this.flushThreshold && !anyMarkActive) {
+      this.flush();
+    }
+  }
+
+  canRead(n) {
+    n = (n !== undefined) ? n : this.startIndex;
+    return this.buffer.length - n > 0;
+  }
+}

package/src/OptionsBuilder.js

@@ -0,0 +1,400 @@
+import { CompactBuilderFactory } from '@nodable/compact-builder';
+import { Expression, ExpressionSet } from 'path-expression-matcher';
+import { ParseError, ErrorCode } from './ParseError.js';
+import { DANGEROUS_PROPERTY_NAMES, criticalProperties } from './util.js';
+
+const defaultOnDangerousProperty = (name) => {
+  if (DANGEROUS_PROPERTY_NAMES.includes(name)) {
+    return "__" + name;
+  }
+  return name;
+};
+
+export const defaultOptions = {
+  // --- skip group ---
+  // Controls which node types are excluded from output
+  skip: {
+    declaration: false,   // Skip <?xml ... ?> declaration
+    pi: false,            // Skip processing instructions (other than declaration)
+    attributes: true,     // Skip all attributes
+    cdata: false,         // Exclude CDATA sections from output entirely
+    comment: false,       // Exclude comments from output entirely
+    nsPrefix: false,      // Strip namespace prefixes (e.g. ns:tag → tag)
+    tags: [],             // Tag paths to skip entirely — content is silently dropped from output
+  },
+
+  // --- nameFor group ---
+  // Property names used when including special nodes in output.
+  nameFor: {
+    text: '#text',  // Property for mixed text content
+    cdata: '',      // '' = merge CDATA into text value
+    comment: '',    // '' = omit comments from output
+  },
+
+  // --- attributes group ---
+  attributes: {
+    booleanType: false,  // Allow valueless attributes (treated as boolean true)
+    groupBy: '',         // Group all attributes under this key; '' = inline with tag
+    prefix: '@_',        // Prepended to attribute names in output
+    suffix: '',          // Appended to attribute names in output
+  },
+
+  // --- tags group ---
+  tags: {
+    unpaired: [],     // Tags that never have a closing tag (e.g. br, img, hr)
+    stopNodes: [],    // Tag paths whose content is captured raw without parsing
+  },
+
+  // --- security ---
+  strictReservedNames: false,
+  onDangerousProperty: defaultOnDangerousProperty,
+
+  // --- filtering (path-expression-matcher) ---
+  only: [], // for future
+
+  // --- DOCTYPE parsing ---
+  // Controls whether DOCTYPE entities are collected and read-time security limits.
+  //
+  //   enabled         — false (default) → DOCTYPE is read (to consume it) but entities
+  //                                        are discarded and never forwarded to output builders
+  //                     true → collect DOCTYPE entities and forward them to the output builder
+  //                     Note: the output builder must have an EntitiesValueParser registered
+  //                     under 'entity' and 'entity' must be in its
+  //                     valueParsers chain for replacement to actually happen.
+  //
+  // Read-time security limits (enforced by DocTypeReader at declaration time):
+  //   maxEntityCount  — max entities declared in a DOCTYPE (default: 100)
+  //   maxEntitySize   — max bytes per entity definition value (default: 10000)
+  //
+  // Replacement-time limits (maxTotalExpansions, maxExpandedLength) are configured
+  // on EntitiesValueParser directly — they are not part of doctypeOptions.
+  doctypeOptions: {
+    enabled: false,
+    maxEntityCount: 100,
+    maxEntitySize: 10000,
+  },
+
+  // --- autoClose ---
+  // Controls parser behaviour when tags are unclosed or mismatched.
+  //
+  //   onEof       — what to do when EOF is reached with open tags still on the stack
+  //                 'throw'    (default) → throw an error
+  //                 'closeAll' → silently close all remaining open tags
+  //
+  //   onMismatch  — what to do when a closing tag doesn't match the current open tag
+  //                 'throw'   (default) → throw an error
+  //                 'recover' → pop the stack toward the nearest matching opener;
+  //                             if no match is found the tag is discarded
+  //                 'discard' → silently ignore the bad closing tag
+  //
+  //   collectErrors — when true, errors are recorded in result.__parseErrors instead
+  //                   of being silently dropped.  Each entry has the shape:
+  //                   { type, tag, expected, line, col, index }
+  //
+  // Shorthand: autoClose: 'html' sets onEof:'closeAll', onMismatch:'discard',
+  // collectErrors:true, and adds the standard HTML void elements to tags.unpaired.
+  autoClose: null,   // null = feature disabled; throws on any malformed input
+
+  // --- limits (DoS prevention) ---
+  // Group structural limits that guard against resource exhaustion.
+  //
+  //   maxNestedTags     — maximum tag nesting depth; throws when exceeded.
+  //                       Prevents stack-overflow attacks via deeply nested XML.
+  //                       Default: null (no limit)
+  //
+  //   maxAttributesPerTag — maximum number of attributes on a single tag.
+  //                         Throws when a tag exceeds this count.
+  //                         Default: null (no limit)
+  //
+  limits: {
+    maxNestedTags: null,
+    maxAttributesPerTag: null,
+  },
+
+  // --- feedable (feed/end and parseStream input options) ---
+  // Controls buffer behaviour for the FeedableSource and StreamSource.
+  //
+  //   maxBufferSize  — maximum number of characters allowed in the buffer at
+  //                    any one time.  Prevents memory exhaustion when a caller
+  //                    feeds data faster than it is consumed.
+  //                    Default: 10 MB (10 * 1024 * 1024 characters)
+  //
+  //   autoFlush      — when true (default), already-processed characters are
+  //                    automatically discarded from the front of the buffer
+  //                    whenever the processed portion exceeds flushThreshold.
+  //                    Keeps memory usage flat for large documents.
+  //
+  //   flushThreshold — number of processed characters that triggers an auto-
+  //                    flush.  Lower values free memory sooner but incur more
+  //                    string-slice operations.  Default: 1024 characters (1 KB)
+  //
+  feedable: {
+    maxBufferSize: 10 * 1024 * 1024,
+    autoFlush: true,
+    flushThreshold: 1024,
+  },
+
+  // --- exitIf ---
+  // Stops parsing as soon as the predicate returns true for the current tag.
+  //
+  // The callback receives a read-only matcher positioned at the just-opened tag:
+  //   exitIf(matcher) → boolean
+  //
+  // When exitIf returns true the parser immediately:
+  //   1. Closes all currently open tags (innermost first) by calling addTextNode()
+  //      and popTag() for each, so the output builder can finalise its tree.
+  //   2. Calls outputBuilder.onExit({ tagDetail, matcher, tagsStack }) so the
+  //      builder can record that the parse was intentionally truncated.
+  //   3. Breaks the parse loop — no further source characters are read.
+  //
+  // The parse call returns the partial-but-consistent output as normal.
+  // No error is thrown.
+  //
+  // Default: null (feature disabled)
+  exitIf: null,
+
+  // --- output ---
+  OutputBuilder: null, //TODO: accept lower case
+};
+
+// All names that should never appear as property keys
+const ALL_RESERVED = new Set([...criticalProperties, ...DANGEROUS_PROPERTY_NAMES]);
+export { ALL_RESERVED as RESERVED_JS_NAMES };
+
+function validatePropertyName(value, optionName) {
+  if (typeof value !== 'string' || value === '') return;
+  if (ALL_RESERVED.has(value)) {
+    throw new ParseError(
+      `SECURITY: '${value}' is a reserved JavaScript keyword and cannot be used as ${optionName}`,
+      ErrorCode.SECURITY_RESERVED_OPTION
+    );
+  }
+}
+
+export const buildOptions = function (options) {
+  // Validate security-sensitive option values BEFORE merging
+  if (options) {
+    if (options.nameFor?.text) validatePropertyName(options.nameFor.text, 'nameFor.text');
+    if (options.nameFor?.cdata) validatePropertyName(options.nameFor.cdata, 'nameFor.cdata');
+    if (options.nameFor?.comment) validatePropertyName(options.nameFor.comment, 'nameFor.comment');
+    if (options.attributes?.prefix) validatePropertyName(options.attributes.prefix, 'attributes.prefix');
+    if (options.attributes?.groupBy) validatePropertyName(options.attributes.groupBy, 'attributes.groupBy');
+
+    // Validate limits option
+    if (options.limits !== undefined && options.limits !== null) {
+      if (typeof options.limits !== 'object') {
+        throw new ParseError(`'limits' must be an object, got ${typeof options.limits}`, ErrorCode.INVALID_INPUT);
+      }
+      const { maxNestedTags, maxAttributesPerTag } = options.limits;
+      if (maxNestedTags !== undefined && maxNestedTags !== null &&
+        (typeof maxNestedTags !== 'number' || !Number.isInteger(maxNestedTags) || maxNestedTags < 1)) {
+        throw new ParseError(`'limits.maxNestedTags' must be a positive integer, got ${maxNestedTags}`, ErrorCode.INVALID_INPUT);
+      }
+      if (maxAttributesPerTag !== undefined && maxAttributesPerTag !== null &&
+        (typeof maxAttributesPerTag !== 'number' || !Number.isInteger(maxAttributesPerTag) || maxAttributesPerTag < 0)) {
+        throw new ParseError(`'limits.maxAttributesPerTag' must be a non-negative integer, got ${maxAttributesPerTag}`, ErrorCode.INVALID_INPUT);
+      }
+    }
+  }
+
+  const finalOptions = deepClone(defaultOptions);
+
+  if (options) {
+    copyProperties(finalOptions, options);
+  }
+
+  if (!finalOptions.OutputBuilder) {
+    finalOptions.OutputBuilder = new CompactBuilderFactory();
+  }
+
+  // Normalize stopNodes and skip.tags entries into Expression objects with config embedded
+  // in Expression.data as { nested, skipEnclosures }. Build a sealed ExpressionSet for
+  // O(1) hot-path matching in the parser.
+  //
+  // Accepted entry forms (identical for both stopNodes and skip.tags):
+  //   "..script"
+  //     → Expression("..script", {}, { nested: false, skipEnclosures: [] })
+  //
+  //   Expression instance
+  //     → re-wrapped with { nested: false, skipEnclosures: [] } in data
+  //
+  //   { expression: "..script", nested?: boolean, skipEnclosures?: [] }
+  //   { expression: Expression,  nested?: boolean, skipEnclosures?: [] }
+  //     → Expression with the given config embedded in .data
+  //
+  // `nested` defaults to false; `skipEnclosures` defaults to [].
+  // The two flags are fully independent — any combination is valid.
+  if (Array.isArray(finalOptions.tags?.stopNodes)) {
+    const stopSet = new ExpressionSet();
+    finalOptions.tags.stopNodes = finalOptions.tags.stopNodes.map(
+      (entry) => normalizeTagEntry(entry, 'stopNodes', stopSet)
+    );
+    stopSet.seal();
+    finalOptions.tags.stopNodesSet = stopSet;
+  }
+
+  if (Array.isArray(finalOptions.skip?.tags)) {
+    const skipSet = new ExpressionSet();
+    finalOptions.skip.tags = finalOptions.skip.tags.map(
+      (entry) => normalizeTagEntry(entry, 'skip.tags', skipSet)
+    );
+    skipSet.seal();
+    finalOptions.skip.tagsSet = skipSet;
+  }
+
+  if (finalOptions.onDangerousProperty === null) {
+    finalOptions.onDangerousProperty = defaultOnDangerousProperty;
+  }
+
+  // Validate exitIf
+  if (finalOptions.exitIf !== null && finalOptions.exitIf !== undefined) {
+    if (typeof finalOptions.exitIf !== 'function') {
+      throw new ParseError(
+        `'exitIf' must be a function, got ${typeof finalOptions.exitIf}`,
+        ErrorCode.INVALID_INPUT,
+      );
+    }
+  }
+
+  // Resolve autoClose: expand the 'html' preset and normalise to an object
+  finalOptions.autoClose = resolveAutoClose(finalOptions.autoClose, finalOptions);
+
+  return finalOptions;
+};
+
+/** Standard HTML void elements — never have a closing tag. */
+const HTML_VOID_ELEMENTS = [
+  'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+  'link', 'meta', 'param', 'source', 'track', 'wbr',
+];
+
+/**
+ * Normalise the raw `autoClose` option value into either null (disabled)
+ * or a fully-resolved options object.
+ *
+ * @param {null|string|object} raw   - Value supplied by the user
+ * @param {object}             opts  - The already-merged final options (mutated for html preset)
+ * @returns {null|object}
+ */
+function resolveAutoClose(raw, opts) {
+  if (!raw) return null;
+
+  if (raw === 'html') {
+    // Apply HTML-specific tag defaults
+    const existingUnpaired = opts.tags.unpaired || [];
+    const merged = [...new Set([...existingUnpaired, ...HTML_VOID_ELEMENTS])];
+    opts.tags = { ...opts.tags, unpaired: merged };
+
+    return {
+      onEof: 'closeAll',
+      onMismatch: 'discard',
+      collectErrors: true,
+    };
+  }
+
+  if (typeof raw === 'string') {
+    // e.g. autoClose: 'closeAll' — treat as shorthand for onEof
+    return {
+      onEof: raw,
+      onMismatch: 'throw',
+      collectErrors: false,
+    };
+  }
+
+  if (typeof raw === 'object') {
+    return {
+      onEof: raw.onEof || 'throw',
+      onMismatch: raw.onMismatch || 'throw',
+      collectErrors: raw.collectErrors || false,
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Normalize one entry from `tags.stopNodes` or `skip.tags` into an Expression
+ * whose `.data` carries `{ nested, skipEnclosures }`, and register it in `set`.
+ *
+ * Accepted forms:
+ *   string                                      → bare pattern, defaults applied
+ *   Expression instance                         → re-wrapped with defaults
+ *   { expression: string|Expression, nested?, skipEnclosures? }
+ *
+ * @param {string|Expression|object} entry
+ * @param {string} optionName  - Used in error messages ("stopNodes" or "skip.tags")
+ * @param {ExpressionSet} set  - The set to register the resulting Expression into
+ * @returns {Expression}
+ */
+function normalizeTagEntry(entry, optionName, set) {
+  let pattern, nested, skipEnclosures;
+
+  if (typeof entry === 'string') {
+    if (entry.length === 0) throw new ParseError(`${optionName} expression cannot be empty`, ErrorCode.INVALID_INPUT);
+    pattern = entry;
+    nested = false;
+    skipEnclosures = [];
+  } else if (entry instanceof Expression) {
+    // Bare Expression — keep its pattern, apply defaults for missing data fields
+    pattern = entry.toString();
+    nested = entry.data?.nested ?? false;
+    skipEnclosures = entry.data?.skipEnclosures ?? [];
+  } else if (entry && typeof entry === 'object' && entry.expression !== undefined) {
+    const raw = entry.expression;
+    if (typeof raw === 'string') {
+      if (raw.length === 0) throw new ParseError(`${optionName} expression cannot be empty`, ErrorCode.INVALID_INPUT);
+      pattern = raw;
+    } else if (raw instanceof Expression) {
+      pattern = raw.toString();
+    } else {
+      throw new ParseError(`${optionName} expression must be a string or Expression instance`, ErrorCode.INVALID_INPUT);
+    }
+    nested = entry.nested === true;
+    skipEnclosures = Array.isArray(entry.skipEnclosures) ? entry.skipEnclosures : [];
+  } else {
+    throw new ParseError(
+      `Invalid ${optionName} entry: expected a string, Expression, or { expression, nested?, skipEnclosures? } object.`,
+      ErrorCode.INVALID_INPUT,
+    );
+  }
+
+  const expr = new Expression(pattern, {}, { nested, skipEnclosures });
+  set.add(expr);
+  return expr;
+}
+
+function deepClone(obj) {
+  if (obj === null || typeof obj !== 'object') return obj;
+  if (Array.isArray(obj)) return obj.map(deepClone);
+  if (obj instanceof RegExp) return obj;     // ← guard
+  if (obj instanceof Expression) return obj; // ← guard — Expression instances are immutable
+  const clone = {};
+  for (const key of Object.keys(obj)) {
+    clone[key] = typeof obj[key] === 'function' ? obj[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 (key === 'OutputBuilder') {
+      target[key] = source[key];
+    } else if (typeof source[key] === 'function') {
+      target[key] = source[key];
+    } else if (source[key] instanceof RegExp) {   // ← guard, before the generic object check
+      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];
+    }
+  }
+}