xml-sax-ts 0.1.3 → 0.3.0

package/README.md

@@ -51,6 +51,62 @@ const root = parseXmlString("<root><a>1</a><b/></root>");
 console.log(root.name); // "root"
 ```
 
+### Project to plain objects
+
+```ts
+import { buildObject, parseXmlString } from "xml-sax-ts";
+
+const root = parseXmlString("<root id='1'><item>1</item><item>2</item></root>");
+const obj = buildObject(root);
+// { "@_id": "1", item: ["1", "2"] }
+```
+
+### Streaming object builder
+
+```ts
+import { ObjectBuilder, XmlSaxParser } from "xml-sax-ts";
+
+const builder = new ObjectBuilder();
+const parser = new XmlSaxParser({
+  onOpenTag: builder.onOpenTag,
+  onText: builder.onText,
+  onCdata: builder.onCdata,
+  onCloseTag: builder.onCloseTag
+});
+
+parser.feed("<root><item>1</item>");
+parser.feed("<item>2</item></root>");
+parser.close();
+
+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
@@ -108,6 +164,42 @@ Convenience function that parses a complete XML string into an `XmlNode` tree us
 
 Low-level tree builder. Attach its `onOpenTag`, `onText`, `onCdata`, and `onCloseTag` methods to a parser, then call `getRoot()` to retrieve the resulting `XmlNode`.
 
+### `buildObject(root, options?)`
+
+Projects an `XmlNode` tree into a plain object. Attributes are prefixed (default `@_`), text is stored under `#text`, repeated elements are arrays, and elements with only text return the text directly.
+
+### `ObjectBuilder`
+
+Streaming builder that produces the same object shape as `buildObject` without building a full `XmlNode` tree. Attach its `onOpenTag`, `onText`, `onCdata`, and `onCloseTag` methods to the parser.
+
+#### `ObjectBuilderOptions`
+
+| 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    |
+| `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.
@@ -127,7 +219,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`
+`OpenTag` · `CloseTag` · `XmlAttribute` · `ProcessingInstruction` · `Doctype` · `XmlNode` · `XmlChild` · `XmlPosition` · `ParserOptions` · `SerializeOptions` · `ObjectBuilderOptions` · `ArrayElementSelector` · `XmlObjectMap` · `XmlObjectValue` · `XmlBuilderOptions` · `XmlInputObject` · `XmlInputValue` · `ObjectToXmlOptions`
 
 ## Features
 

package/dist/index.cjs

@@ -723,10 +723,371 @@ function escapeAttribute(value) {
   return escapeText(value).replace(/"/g, """);
 }
 
+// src/object.ts
+var DEFAULT_OBJECT_OPTIONS = {
+  attributePrefix: "@_",
+  textKey: "#text",
+  stripNamespaces: false,
+  coalesceText: true
+};
+function stripNamespace(name) {
+  const index = name.indexOf(":");
+  if (index === -1) {
+    return name;
+  }
+  return name.slice(index + 1);
+}
+function resolveName(value) {
+  if (typeof value !== "string") {
+    return {
+      name: value.name,
+      localName: value.local,
+      prefix: value.prefix,
+      uri: value.uri
+    };
+  }
+  const index = value.indexOf(":");
+  if (index === -1) {
+    return { name: value, localName: value, prefix: "", uri: "" };
+  }
+  return {
+    name: value,
+    localName: value.slice(index + 1),
+    prefix: value.slice(0, index),
+    uri: ""
+  };
+}
+function buildObject(root, options = {}) {
+  const settings = buildSettings(options);
+  return buildNode(root, settings, []);
+}
+function buildXmlNode(obj, options = {}) {
+  const settings = buildXmlSettings(options);
+  const root = resolveRoot(obj, settings);
+  const rootName = normalizeName(root.name, settings);
+  return buildElement(rootName, root.value, settings, []);
+}
+function objectToXml(obj, options = {}) {
+  const node = buildXmlNode(obj, options);
+  return serializeXml(node, options);
+}
+var ObjectBuilder = class {
+  constructor(options = {}) {
+    this.stack = [];
+    this.root = null;
+    this.rootName = null;
+    this.onOpenTag = (tag) => {
+      const name = normalizeName(tag.name, this.options);
+      const attributes = normalizeAttributes(tag.attributes, this.options);
+      const state = {
+        name,
+        attributes,
+        textParts: [],
+        children: /* @__PURE__ */ Object.create(null)
+      };
+      this.rootName ?? (this.rootName = name);
+      this.stack.push(state);
+    };
+    this.onText = (text) => {
+      if (!text) {
+        return;
+      }
+      const current = this.stack[this.stack.length - 1];
+      if (!current) {
+        return;
+      }
+      current.textParts.push(text);
+    };
+    this.onCdata = (text) => {
+      this.onText(text);
+    };
+    this.onCloseTag = () => {
+      const state = this.stack.pop();
+      if (!state) {
+        return;
+      }
+      const value = finalizeElement(state, this.options);
+      const parent = this.stack[this.stack.length - 1];
+      if (!parent) {
+        this.root = value;
+        return;
+      }
+      const path = this.stack.map((entry) => entry.name);
+      addChild(parent.children, state.name, value, this.options, path);
+    };
+    this.options = buildSettings(options);
+  }
+  getResult() {
+    if (this.root === null) {
+      throw new Error("No root element found");
+    }
+    return this.root;
+  }
+  getRootName() {
+    if (!this.rootName) {
+      throw new Error("No root element found");
+    }
+    return this.rootName;
+  }
+};
+function buildSettings(options) {
+  return { ...DEFAULT_OBJECT_OPTIONS, ...options };
+}
+function buildXmlSettings(options) {
+  return { ...DEFAULT_OBJECT_OPTIONS, ...options };
+}
+function buildNode(node, options, path) {
+  const name = normalizeName(node.name, options);
+  const attributes = normalizeAttributeMap(node.attributes ?? {}, options);
+  const state = {
+    attributes,
+    textParts: [],
+    children: /* @__PURE__ */ Object.create(null)
+  };
+  const children = node.children ?? [];
+  for (const child of children) {
+    if (typeof child === "string") {
+      if (child) {
+        state.textParts.push(child);
+      }
+      continue;
+    }
+    const value = buildNode(child, options, [...path, name]);
+    const childName = normalizeName(child.name, options);
+    addChild(state.children, childName, value, options, [...path, name]);
+  }
+  return finalizeElement(state, options);
+}
+function normalizeName(name, options) {
+  if (options.stripNamespaces) {
+    return stripNamespace(name);
+  }
+  return name;
+}
+function normalizeXmlName(name, options) {
+  if (options.stripNamespaces) {
+    return stripNamespace(name);
+  }
+  return name;
+}
+function normalizeAttributes(attributes, options) {
+  const result = /* @__PURE__ */ Object.create(null);
+  for (const [key, attr] of Object.entries(attributes)) {
+    const name = normalizeName(key, options);
+    result[name] = attr.value;
+  }
+  return result;
+}
+function normalizeAttributeMap(attributes, options) {
+  const result = /* @__PURE__ */ Object.create(null);
+  for (const [key, value] of Object.entries(attributes)) {
+    const name = normalizeName(key, options);
+    result[name] = value;
+  }
+  return result;
+}
+function addChild(target, name, value, options, path) {
+  const forcedArray = shouldForceArray(name, path, options);
+  const existing = target[name];
+  if (existing === void 0) {
+    target[name] = forcedArray ? [value] : value;
+    return;
+  }
+  if (Array.isArray(existing)) {
+    existing.push(value);
+    return;
+  }
+  target[name] = [existing, value];
+}
+function shouldForceArray(name, path, options) {
+  const rule = options.arrayElements;
+  if (!rule) {
+    return false;
+  }
+  if (rule instanceof Set) {
+    return rule.has(name);
+  }
+  return rule(name, path);
+}
+function resolveRoot(obj, options) {
+  if (isRecord(obj)) {
+    const keys = Object.keys(obj);
+    if (keys.length === 1) {
+      const name = keys[0] ?? "";
+      return { name, value: obj[name] };
+    }
+  }
+  if (!options.rootName) {
+    throw new Error("Root element name is required when object has multiple keys");
+  }
+  return { name: options.rootName, value: obj };
+}
+function buildElement(name, value, options, path) {
+  const attributes = /* @__PURE__ */ Object.create(null);
+  const children = [];
+  const nextPath = [...path, name];
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      appendContent(children, item, options, nextPath);
+    }
+    return finalizeNode(name, attributes, children);
+  }
+  if (isPrimitive(value)) {
+    const text = coerceText(value);
+    if (text !== null) {
+      children.push(text);
+    }
+    return finalizeNode(name, attributes, children);
+  }
+  if (isRecord(value)) {
+    for (const [key, entryValue] of Object.entries(value)) {
+      if (isAttributeKey(key, options)) {
+        const attrName = normalizeXmlName(key.slice(options.attributePrefix.length), options);
+        const attrValue = coerceText(entryValue);
+        if (attrValue !== null) {
+          attributes[attrName] = attrValue;
+        }
+        continue;
+      }
+      if (key === options.textKey) {
+        appendText(children, entryValue, options);
+        continue;
+      }
+      const childName = normalizeXmlName(key, options);
+      addChildElements(children, childName, entryValue, options, nextPath);
+    }
+  }
+  return finalizeNode(name, attributes, children);
+}
+function addChildElements(children, name, value, options, path) {
+  const forcedArray = shouldForceArray(name, path, options);
+  const items = Array.isArray(value) ? value : forcedArray ? [value] : [value];
+  for (const item of items) {
+    if (item === void 0 || item === null) {
+      children.push({ name });
+      continue;
+    }
+    children.push(buildElement(name, item, options, path));
+  }
+}
+function appendContent(children, value, options, path) {
+  if (value === void 0 || value === null) {
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      appendContent(children, item, options, path);
+    }
+    return;
+  }
+  if (isPrimitive(value)) {
+    const text = coerceText(value);
+    if (text !== null) {
+      children.push(text);
+    }
+    return;
+  }
+  if (isRecord(value)) {
+    for (const [key, entryValue] of Object.entries(value)) {
+      const childName = normalizeXmlName(key, options);
+      addChildElements(children, childName, entryValue, options, path);
+    }
+  }
+}
+function appendText(children, value, options) {
+  if (value === void 0 || value === null) {
+    return;
+  }
+  if (Array.isArray(value)) {
+    const parts = value.map((item) => coerceText(item)).filter((item) => item !== null);
+    if (parts.length === 0) {
+      return;
+    }
+    if (options.coalesceText) {
+      children.push(parts.join(""));
+      return;
+    }
+    for (const part of parts) {
+      children.push(part);
+    }
+    return;
+  }
+  const text = coerceText(value);
+  if (text !== null) {
+    children.push(text);
+  }
+}
+function finalizeNode(name, attributes, children) {
+  const node = { name };
+  if (Object.keys(attributes).length > 0) {
+    node.attributes = attributes;
+  }
+  if (children.length > 0) {
+    node.children = children;
+  }
+  return node;
+}
+function isAttributeKey(key, options) {
+  if (!options.attributePrefix) {
+    return false;
+  }
+  return key.startsWith(options.attributePrefix) && key.length > options.attributePrefix.length;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPrimitive(value) {
+  return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+function coerceText(value) {
+  if (value === void 0 || value === null) {
+    return null;
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  return null;
+}
+function finalizeElement(state, options) {
+  const hasAttributes = Object.keys(state.attributes).length > 0;
+  const hasChildren = Object.keys(state.children).length > 0;
+  const hasText = state.textParts.length > 0;
+  const textValue = options.coalesceText ? state.textParts.join("") : state.textParts.length <= 1 ? state.textParts[0] ?? "" : state.textParts.slice();
+  if (!hasAttributes && !hasChildren) {
+    if (!hasText) {
+      return "";
+    }
+    return textValue;
+  }
+  const result = /* @__PURE__ */ Object.create(null);
+  for (const [key, value] of Object.entries(state.attributes)) {
+    result[`${options.attributePrefix}${key}`] = value;
+  }
+  for (const [key, value] of Object.entries(state.children)) {
+    result[key] = value;
+  }
+  if (hasText) {
+    result[options.textKey] = textValue;
+  }
+  return result;
+}
+
+exports.ObjectBuilder = ObjectBuilder;
 exports.TreeBuilder = TreeBuilder;
 exports.XmlSaxError = XmlSaxError;
 exports.XmlSaxParser = XmlSaxParser;
+exports.buildObject = buildObject;
+exports.buildXmlNode = buildXmlNode;
+exports.objectToXml = objectToXml;
 exports.parseXmlString = parseXmlString;
+exports.resolveName = resolveName;
 exports.serializeXml = serializeXml;
+exports.stripNamespace = stripNamespace;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map