@eksml/xml 0.1.0

package/src/converters/fromLossy.ts

@@ -0,0 +1,180 @@
+/**
+ * fromLossy — convert a lossy JS object back to a TNode DOM tree.
+ *
+ * This is the inverse of `lossy()`. Because the lossy format does not preserve
+ * sibling order between different tag names, the reconstruction is best-effort:
+ * elements appear in JS object key insertion order, and arrays expand in
+ * sequence. Mixed content (`$$` arrays) preserves interleaving exactly.
+ *
+ * Lossy format rules (reversed):
+ * - `null` → empty element (no attributes, no children)
+ * - `string` → text-only element (one string child)
+ * - `$`-prefixed keys → attributes (prefix stripped)
+ * - `$$` array → mixed content (strings become text, objects become elements)
+ * - Non-`$` keys → element children (arrays expand to repeated siblings)
+ * - Top-level single-key object → single root element
+ * - Top-level array → multiple root elements
+ *
+ * @example
+ * ```ts
+ * import { fromLossy } from "@eksml/xml/from-lossy";
+ * import { lossy } from "@eksml/xml/lossy";
+ * import { write } from "@eksml/xml/writer";
+ *
+ * const obj = lossy('<root><item>hello</item><item>world</item></root>');
+ * const dom = fromLossy(obj);
+ * const xml = write(dom);
+ * ```
+ */
+
+import type { TNode } from '#src/parser.ts';
+import type {
+  LossyValue,
+  LossyObject,
+  LossyMixedEntry,
+} from '#src/converters/lossy.ts';
+// @generated:char-codes:begin
+const DOLLAR = 36; // $
+// @generated:char-codes:end
+
+/**
+ * Convert a lossy JS object back to a `(TNode | string)[]` DOM tree.
+ *
+ * Accepts the same shapes that `lossy()` returns:
+ * - A single `LossyValue` (e.g. `{ root: { ... } }`)
+ * - An array of `LossyValue` (multiple roots)
+ *
+ * @param input - A lossy value or array of lossy values.
+ * @returns A DOM array suitable for `write()` or further processing.
+ */
+export function fromLossy(
+  input: LossyValue | LossyValue[],
+): (TNode | string)[] {
+  // Array of top-level values
+  if (Array.isArray(input)) {
+    const result: (TNode | string)[] = [];
+    for (let i = 0; i < input.length; i++) {
+      const item = input[i]!;
+      if (typeof item === 'string') {
+        result.push(item);
+      } else if (item === null) {
+        // Top-level null — unusual, skip
+        continue;
+      } else {
+        // Each object in the array is { tagName: value }
+        convertTopLevelObject(item, result);
+      }
+    }
+    return result;
+  }
+
+  // Single value
+  if (input === null || typeof input === 'string') {
+    // Bare null or string at top level — can't form a TNode without a tag name
+    return typeof input === 'string' ? [input] : [];
+  }
+
+  // Single-root object: { rootTag: value }
+  const result: (TNode | string)[] = [];
+  convertTopLevelObject(input, result);
+  return result;
+}
+
+/**
+ * Convert a top-level `{ tagName: value }` object into TNode(s) and push
+ * them onto the result array.
+ */
+function convertTopLevelObject(
+  object: LossyObject,
+  result: (TNode | string)[],
+): void {
+  const keys = Object.keys(object);
+  for (let i = 0; i < keys.length; i++) {
+    const tagName = keys[i]!;
+    result.push(convertElement(tagName, object[tagName]!));
+  }
+}
+
+/**
+ * Convert a tag name + lossy value into a TNode.
+ */
+function convertElement(
+  tagName: string,
+  value: LossyValue | LossyValue[] | LossyMixedEntry[],
+): TNode {
+  // null → empty element
+  if (value === null) {
+    return { tagName, attributes: null, children: [] };
+  }
+
+  // string → text-only element
+  if (typeof value === 'string') {
+    return { tagName, attributes: null, children: [value] };
+  }
+
+  // Array → this is a repeated-sibling array at the parent level,
+  // but convertElement is called per-value, so arrays here shouldn't
+  // normally occur. Defensive: treat as first element.
+  if (Array.isArray(value)) {
+    // This case is handled by the caller expanding arrays.
+    // If somehow called directly, use first item.
+    return convertElement(tagName, value[0] ?? null);
+  }
+
+  // LossyObject → extract attributes ($-prefixed), check for $$ mixed content,
+  // then process element-only children
+  const objectValue = value as LossyObject;
+  const objectKeys = Object.keys(objectValue);
+
+  let attributes: Record<string, string | null> | null = null;
+  const children: (TNode | string)[] = [];
+  let hasMixed = false;
+
+  for (let i = 0; i < objectKeys.length; i++) {
+    const key = objectKeys[i]!;
+
+    if (key === '$$') {
+      // Mixed content array
+      hasMixed = true;
+      const mixedArray = objectValue.$$ as LossyMixedEntry[];
+      for (let j = 0; j < mixedArray.length; j++) {
+        const mixedEntry = mixedArray[j]!;
+        if (typeof mixedEntry === 'string') {
+          children.push(mixedEntry);
+        } else {
+          // { tagName: value } — single-key object
+          const entryKeys = Object.keys(mixedEntry);
+          const entryTagName = entryKeys[0]!;
+          children.push(
+            convertElement(
+              entryTagName,
+              (mixedEntry as LossyObject)[entryTagName]!,
+            ),
+          );
+        }
+      }
+    } else if (key.charCodeAt(0) === DOLLAR) {
+      // Attribute — strip the $ prefix
+      if (attributes === null) {
+        attributes = Object.create(null) as Record<string, string | null>;
+      }
+      const attributeName = key.substring(1);
+      const attributeValue = objectValue[key];
+      attributes[attributeName] =
+        attributeValue === null ? null : String(attributeValue);
+    } else {
+      // Element child(ren)
+      const childValue = objectValue[key]!;
+      if (Array.isArray(childValue)) {
+        // Repeated siblings
+        for (let j = 0; j < childValue.length; j++) {
+          children.push(convertElement(key, childValue[j]!));
+        }
+      } else {
+        children.push(convertElement(key, childValue as LossyValue));
+      }
+    }
+  }
+
+  return { tagName, attributes, children };
+}

package/src/converters/lossless.ts

@@ -0,0 +1,116 @@
+/**
+ * lossless — XML-to-JSON converter producing an order-preserving format.
+ *
+ * Each element becomes a single-key object `{ tagName: children[] }`.
+ * Text nodes become `{ $text: "..." }`.
+ * Attributes become `{ $attr: { ... } }` as the first entry in the children array.
+ * Comments (when kept) become `{ $comment: "..." }`.
+ *
+ * All marker keys are valid JS identifiers so you can use dot notation:
+ * `entry.$attr.id`, `entry.$text`, `entry.$comment`.
+ *
+ * The format preserves element order, mixed content, and attributes losslessly,
+ * and is fully JSON-serializable.
+ *
+ * @example
+ * ```ts
+ * import { lossless } from "@eksml/xml/lossless";
+ *
+ * const result = lossless('<root attr="1"><item>hell<b>o</b></item></root>');
+ * // [
+ * //   { "root": [
+ * //     { $attr: { "attr": "1" } },
+ * //     { "item": [
+ * //       { $text: "hell" },
+ * //       { "b": [{ $text: "o" }] }
+ * //     ]}
+ * //   ]}
+ * // ]
+ * ```
+ */
+
+import { parse, type TNode, type ParseOptions } from '#src/parser.ts';
+
+/** A single entry in the JSON output array. */
+export type LosslessEntry =
+  | { [tagName: string]: LosslessEntry[] }
+  | { $text: string }
+  | { $attr: Record<string, string | null> }
+  | { $comment: string };
+
+/** Options for lossless. */
+export interface LosslessOptions extends ParseOptions {}
+
+function convertNode(node: TNode): LosslessEntry {
+  const children: LosslessEntry[] = [];
+
+  // Attributes go first as { $attr: { ... } }
+  if (node.attributes !== null) {
+    children.push({ $attr: node.attributes });
+  }
+
+  // Then child nodes
+  for (let i = 0; i < node.children.length; i++) {
+    const child = node.children[i]!;
+    if (typeof child === 'string') {
+      children.push(convertString(child));
+    } else {
+      children.push(convertNode(child));
+    }
+  }
+
+  return { [node.tagName]: children };
+}
+
+function convertString(text: string): LosslessEntry {
+  // Comments from parse() come as "<!-- ... -->"
+  if (text.startsWith('<!--') && text.endsWith('-->')) {
+    return { $comment: text.substring(4, text.length - 3) };
+  }
+  return { $text: text };
+}
+
+/**
+ * Convert a single `TNode | string` item into its lossless representation.
+ *
+ * - `TNode` → `{ tagName: [ ...children ] }`
+ * - `string` → `{ $text: "..." }` or `{ $comment: "..." }`
+ *
+ * Used internally by `XmlParseStream` when `output: 'lossless'` is set.
+ *
+ * @internal
+ */
+export function convertItemToLossless(item: TNode | string): LosslessEntry {
+  if (typeof item === 'string') return convertString(item);
+  return convertNode(item);
+}
+
+/**
+ * Parse an XML/HTML string or convert a pre-parsed DOM tree into an
+ * order-preserving JSON-friendly structure.
+ *
+ * @param input - An XML/HTML string, or a pre-parsed `(TNode | string)[]` DOM array
+ * @param options - Parsing options (only used when `input` is a string)
+ * @returns Array of top-level JSON entries
+ */
+export function lossless(
+  input: string,
+  options?: LosslessOptions,
+): LosslessEntry[];
+export function lossless(input: (TNode | string)[]): LosslessEntry[];
+export function lossless(
+  input: string | (TNode | string)[],
+  options?: LosslessOptions,
+): LosslessEntry[] {
+  const dom = typeof input === 'string' ? parse(input, { ...options }) : input;
+  const result: LosslessEntry[] = [];
+  for (let i = 0; i < dom.length; i++) {
+    const node = dom[i]!;
+    if (typeof node === 'string') {
+      result.push(convertString(node));
+    } else {
+      result.push(convertNode(node));
+    }
+  }
+  return result;
+}

package/src/converters/lossy.ts

@@ -0,0 +1,274 @@
+/**
+ * lossy — simplified lossy XML-to-JS object converter.
+ *
+ * Produces the most compact JS object representation possible. Element
+ * ordering between different tag names is not preserved. The format rules are:
+ *
+ * - **Text-only element**: collapses to a plain string value.
+ *   `<name>text</name>` → `{ "name": "text" }`
+ *
+ * - **Empty/void element**: collapses to `null`.
+ *   `<br/>` → `{ "br": null }`
+ *
+ * - **Attributes**: prefixed with `$` on the element object.
+ *   `<a href="/">link</a>` → `{ "a": { $href: "/", $$: ["link"] } }`
+ *
+ * - **Mixed content** (text + child elements): children go into an ordered
+ *   `$$` array preserving exact interleaving of text and element objects.
+ *   `<p>Hello <b>world</b></p>` → `{ "p": { $$: ["Hello ", { "b": "world" }] } }`
+ *
+ * - **Element-only children** (no text): keyed object with tag names.
+ *   `<root><a>1</a><b>2</b></root>` → `{ "root": { "a": "1", "b": "2" } }`
+ *
+ * - **Repeated same-name siblings**: become an array.
+ *   Two `<item>` → `"item": [val1, val2]`; one `<item>` → `"item": val1`
+ *
+ * All marker keys are valid JS identifiers so you can use dot notation:
+ * `node.$href`, `node.$$`, etc.
+ *
+ * @example
+ * ```ts
+ * import { lossy } from "@eksml/xml/lossy";
+ *
+ * const result = lossy(`
+ *   <thing>
+ *     <second with="attributes">Text</second>
+ *     <third>More text</third>
+ *     <second another="attribute">Even more text
+ *       <fourth>Nested text</fourth>
+ *     </second>
+ *   </thing>
+ * `);
+ * // {
+ * //   "thing": {
+ * //     "second": [
+ * //       { $with: "attributes", $$: ["Text"] },
+ * //       { $another: "attribute", $$: ["Even more text\n      ", { "fourth": "Nested text" }] }
+ * //     ],
+ * //     "third": "More text"
+ * //   }
+ * // }
+ * ```
+ */
+
+import { parse, type TNode, type ParseOptions } from '#src/parser.ts';
+// @generated:char-codes:begin
+const DOLLAR = 36; // $
+// @generated:char-codes:end
+
+/** Options for lossy. */
+export interface LossyOptions extends ParseOptions {}
+
+/** The value of a converted element — null (empty), string, or an object with keys. */
+export type LossyValue = null | string | LossyObject;
+
+/** An element converted to a keyed object. */
+export interface LossyObject {
+  [key: string]: LossyValue | LossyValue[] | LossyMixedEntry[];
+}
+
+/** An entry in a `$$` mixed-content array. */
+export type LossyMixedEntry = string | { [tagName: string]: LossyValue };
+
+/**
+ * Convert a single TNode into its simplified lossy value.
+ *
+ * Single-pass algorithm: starts optimistically building an element-only object,
+ * and upgrades to mixed-content ($$ array) if text nodes are encountered
+ * alongside element nodes (or attributes exist with text).
+ */
+function convertNode(node: TNode): LossyValue {
+  const children = node.children;
+  const childrenLength = children ? children.length : 0;
+  const attributes = node.attributes;
+  const hasAttributes = attributes !== null;
+
+  // --- Empty element ---
+  if (childrenLength === 0 && !hasAttributes) {
+    return null;
+  }
+
+  // --- Text-only element, no attributes ---
+  if (
+    childrenLength === 1 &&
+    typeof children[0] === 'string' &&
+    !hasAttributes
+  ) {
+    return children[0];
+  }
+
+  // --- Build object with attributes ---
+  // Use null-prototype object to prevent __proto__ / constructor pollution
+  const elementObject: LossyObject = Object.create(null);
+
+  if (hasAttributes) {
+    for (const key in attributes) {
+      elementObject['$' + key] = attributes[key]!;
+    }
+  }
+
+  if (childrenLength === 0) {
+    // Empty element with attributes only
+    return elementObject;
+  }
+
+  // --- Single-pass: build element-only object, upgrade to mixed if needed ---
+  // Track whether we've seen elements and/or text so far.
+  // When text appears alongside elements (or attrs), switch to $$ mode,
+  // retroactively converting already-processed children.
+  let hasElements = false;
+  let hasText = false;
+  let mixed: LossyMixedEntry[] | null = null;
+
+  for (let i = 0; i < childrenLength; i++) {
+    const child = children[i]!;
+    if (typeof child === 'string') {
+      hasText = true;
+      if (mixed !== null) {
+        // Already in mixed mode
+        mixed.push(child);
+      } else if (hasElements || hasAttributes) {
+        // Upgrade to mixed mode — retroactively convert prior children.
+        // Remove element keys that were speculatively added to elementObject.
+        for (const propertyKey in elementObject) {
+          if (propertyKey.charCodeAt(0) !== DOLLAR)
+            delete elementObject[propertyKey]; // keep $-prefixed attrs
+        }
+        mixed = [];
+        for (let j = 0; j < i; j++) {
+          const previousChild = children[j]!;
+          if (typeof previousChild === 'string') {
+            mixed.push(previousChild);
+          } else {
+            mixed.push({ [previousChild.tagName]: convertNode(previousChild) });
+          }
+        }
+        mixed.push(child);
+      }
+      // If !hasElements && !hasAttributes, we're still in potential text-only mode
+    } else {
+      if (!hasElements && hasText && !hasAttributes) {
+        // First element after text-only so far — upgrade to mixed mode
+        hasElements = true;
+        mixed = [];
+        for (let j = 0; j < i; j++) {
+          mixed.push(children[j] as string);
+        }
+        mixed.push({ [child.tagName]: convertNode(child) });
+        continue;
+      }
+      hasElements = true;
+      const tag = child.tagName;
+      const convertedValue = convertNode(child);
+      if (mixed !== null) {
+        mixed.push({ [tag]: convertedValue });
+      } else {
+        if (!(tag in elementObject)) {
+          elementObject[tag] = convertedValue;
+        } else if (!Array.isArray(elementObject[tag])) {
+          elementObject[tag] = [
+            elementObject[tag] as LossyValue,
+            convertedValue,
+          ];
+        } else {
+          (elementObject[tag] as LossyValue[]).push(convertedValue);
+        }
+      }
+    }
+  }
+
+  // If we switched to mixed mode, attach and return
+  if (mixed !== null) {
+    elementObject.$$ = mixed;
+    return elementObject;
+  }
+
+  // If we had elements, elementObject is already populated — return it
+  if (hasElements) {
+    return elementObject;
+  }
+
+  // --- Text-only, no attributes, multiple text nodes (edge case) ---
+  let text = '';
+  for (let i = 0; i < childrenLength; i++) {
+    text += children[i] as string;
+  }
+  return text;
+}
+
+/**
+ * Convert a single `TNode | string` item into its lossy representation.
+ *
+ * - `TNode` → `{ tagName: convertedValue }` (same shape as the multi-root
+ *   branch of `lossy()`)
+ * - `string` → passed through as-is
+ *
+ * Used internally by `XmlParseStream` when `output: 'lossy'` is set.
+ *
+ * @internal
+ */
+export function convertItemToLossy(item: TNode | string): LossyValue {
+  if (typeof item === 'string') return item;
+  return { [item.tagName]: convertNode(item) } as LossyObject;
+}
+
+/**
+ * Parse an XML/HTML string or convert a pre-parsed DOM tree into the most
+ * simplified lossy JS object format.
+ *
+ * @param input - An XML/HTML string, or a pre-parsed `(TNode | string)[]` DOM array
+ * @param options - Parsing options (only used when `input` is a string)
+ * @returns A LossyValue representing the document. For a single root element
+ *          this is typically `{ rootTag: ... }`. For multiple top-level nodes
+ *          an array is returned.
+ */
+export function lossy(
+  input: string,
+  options?: LossyOptions,
+): LossyValue | LossyValue[];
+export function lossy(input: (TNode | string)[]): LossyValue | LossyValue[];
+export function lossy(
+  input: string | (TNode | string)[],
+  options?: LossyOptions,
+): LossyValue | LossyValue[] {
+  const dom = typeof input === 'string' ? parse(input, { ...options }) : input;
+
+  // Filter out whitespace-only top-level text and processing instructions
+  // (e.g. <?xml version="1.0"?>) which are metadata, not content.
+  const nodes: (TNode | string)[] = [];
+  for (let i = 0; i < dom.length; i++) {
+    const node = dom[i]!;
+    if (typeof node === 'string') {
+      // Keep non-whitespace text at top level
+      if (node.trim().length > 0) {
+        nodes.push(node);
+      }
+    } else if (node.tagName[0] === '?') {
+      // Skip processing instructions (<?xml?>, <?xsl?>, etc.)
+      continue;
+    } else {
+      nodes.push(node);
+    }
+  }
+
+  // Single root element — return as { rootTag: value }
+  if (nodes.length === 1) {
+    const node = nodes[0]!;
+    if (typeof node === 'string') {
+      return node;
+    }
+    return { [node.tagName]: convertNode(node) } as LossyObject;
+  }
+
+  // Multiple top-level nodes — return array
+  const result: LossyValue[] = [];
+  for (let i = 0; i < nodes.length; i++) {
+    const node = nodes[i]!;
+    if (typeof node === 'string') {
+      result.push(node);
+    } else {
+      result.push({ [node.tagName]: convertNode(node) } as LossyObject);
+    }
+  }
+  return result;
+}