@elaraai/east-node-io 0.0.1-beta.1 → 0.0.1-beta.11

package/dist/format/xml.d.ts

@@ -0,0 +1,302 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { BlobType, RecursiveType, StructType, StringType, DictType, ArrayType, VariantType, BooleanType, OptionType, type ValueTypeOf } from "@elaraai/east";
+import type { PlatformFunction } from "@elaraai/east/internal";
+/**
+ * XmlNode represents an XML element with its tag, attributes, and children.
+ *
+ * Children can be either TEXT nodes (string content) or ELEMENT nodes (nested XML elements).
+ * This recursive structure allows representing arbitrary XML trees.
+ */
+export declare const XmlNode: RecursiveType<StructType<{
+    tag: StringType;
+    attributes: DictType<StringType, StringType>;
+    children: ArrayType<VariantType<{
+        TEXT: StringType;
+        ELEMENT: import("@elaraai/east").RecursiveTypeMarker;
+    }>>;
+}>>;
+export type XmlNodeValue = ValueTypeOf<typeof XmlNode>;
+export declare const XmlParseConfig: StructType<{
+    preserveWhitespace: BooleanType;
+    decodeEntities: BooleanType;
+}>;
+export declare const XmlSerializeConfig: StructType<{
+    indent: OptionType<StringType>;
+    includeXmlDeclaration: BooleanType;
+    encodeEntities: BooleanType;
+    selfClosingTags: BooleanType;
+}>;
+/**
+ * Parses XML data from a binary blob into a recursive tree structure.
+ *
+ * Converts XML-formatted binary data into an {@link XmlNode} recursive structure,
+ * where each node contains a tag name, attributes dictionary, and children array.
+ * Children can be either TEXT nodes (string content) or ELEMENT nodes (nested elements).
+ *
+ * Supports XML declarations, namespaces (as attributes), CDATA sections,
+ * entity decoding, comments (ignored), processing instructions (ignored),
+ * and configurable whitespace handling.
+ *
+ * This is a platform function for the East language, enabling XML parsing
+ * in East programs running on Node.js.
+ *
+ * @param blob - The XML data as a binary blob (UTF-8 encoded)
+ * @param config - Parsing configuration including whitespace and entity handling options
+ * @returns An {@link XmlNode} representing the root element of the XML document
+ *
+ * @throws {EastError} When XML is malformed with specific error messages:
+ * - "Expected '<' at line N, column M" - Missing opening tag bracket
+ * - "Invalid tag name at line N, column M" - Tag name contains invalid characters
+ * - "Expected '=' after attribute name at line N, column M" - Missing equals in attribute
+ * - "Expected quote for attribute value at line N, column M" - Attribute value not quoted
+ * - "Unclosed attribute value at line N, column M" - Missing closing quote
+ * - "Expected '>' at line N, column M" - Missing closing bracket
+ * - "Mismatched closing tag: expected '</X>', found '</Y>' at line N, column M" - Tag mismatch
+ * - "Expected '>' in closing tag at line N, column M" - Malformed closing tag
+ * - "Unclosed comment at line N, column M" - Comment not properly closed
+ * - "Unclosed CDATA section at line N, column M" - CDATA not properly closed
+ * - "Empty XML document" - No root element found
+ *
+ * @example
+ * ```ts
+ * const parseXML = East.function([BlobType], XmlNode, ($, xmlBlob) => {
+ *     const config = $.const(East.value({
+ *         preserveWhitespace: false,
+ *         decodeEntities: true,
+ *     }, XmlParseConfig));
+ *
+ *     return xml_parse(xmlBlob, config);
+ *     // Returns: { tag: "book", attributes: {"id": "123"}, children: [...] }
+ * });
+ * ```
+ *
+ * @remarks
+ * - Skips XML declarations (`<?xml version="1.0"?>`) and processing instructions
+ * - Ignores comments (`<!-- comment -->`) - they are not preserved
+ * - Handles CDATA sections (`<![CDATA[...]]>`) as text without entity decoding
+ * - Decodes predefined entities (`&lt;`, `&gt;`, `&amp;`, `&quot;`, `&apos;`)
+ * - Decodes numeric entities (decimal `&#65;` and hexadecimal `&#x41;`)
+ * - Namespaces are treated as regular attributes (e.g., `xmlns:foo="..."`)
+ * - Preserves namespace prefixes in tag names (e.g., `foo:element`)
+ * - Skips UTF-8 BOM (0xEF 0xBB 0xBF) if present at start
+ * - Tracks line and column numbers for precise error reporting
+ */
+export declare const xml_parse: import("@elaraai/east").PlatformDefinition<[BlobType, StructType<{
+    preserveWhitespace: BooleanType;
+    decodeEntities: BooleanType;
+}>], RecursiveType<StructType<{
+    tag: StringType;
+    attributes: DictType<StringType, StringType>;
+    children: ArrayType<VariantType<{
+        TEXT: StringType;
+        ELEMENT: import("@elaraai/east").RecursiveTypeMarker;
+    }>>;
+}>>>;
+/**
+ * Serializes a recursive XML tree structure into XML-formatted binary data.
+ *
+ * Converts an {@link XmlNode} recursive structure into XML-formatted binary data.
+ * Supports configurable indentation, XML declarations, entity encoding,
+ * and self-closing tag formatting.
+ *
+ * This is a platform function for the East language, enabling XML serialization
+ * in East programs running on Node.js.
+ *
+ * @param node - The {@link XmlNode} root element to serialize
+ * @param config - Serialization configuration including indentation and formatting options
+ * @returns A binary blob containing the XML-formatted data (UTF-8 encoded)
+ *
+ * @example
+ * ```ts
+ * const serializeXML = East.function([XmlNode], BlobType, ($, doc) => {
+ *     const config = $.const(East.value({
+ *         indent: variant('some', "  "),
+ *         includeXmlDeclaration: true,
+ *         encodeEntities: true,
+ *         selfClosingTags: true,
+ *     }, XmlSerializeConfig));
+ *
+ *     return xml_serialize(doc, config);
+ *     // Returns blob that decodes to:
+ *     // <?xml version="1.0" encoding="UTF-8"?>
+ *     // <book id="123">
+ *     //   <title>East Guide</title>
+ *     // </book>
+ * });
+ * ```
+ *
+ * @remarks
+ * - Automatically encodes special characters (`<`, `>`, `&`, `"`, `'`) when encodeEntities is true
+ * - Attributes are serialized in the order they appear in the dictionary (sorted)
+ * - Empty elements are serialized as self-closing tags (`<br/>`) when selfClosingTags is true
+ * - Mixed content (text and elements) avoids extra newlines for simple text-only content
+ * - Indentation is applied recursively to nested elements
+ * - XML declaration includes `version="1.0"` and `encoding="UTF-8"` when enabled
+ */
+export declare const xml_serialize: import("@elaraai/east").PlatformDefinition<[RecursiveType<StructType<{
+    tag: StringType;
+    attributes: DictType<StringType, StringType>;
+    children: ArrayType<VariantType<{
+        TEXT: StringType;
+        ELEMENT: import("@elaraai/east").RecursiveTypeMarker;
+    }>>;
+}>>, StructType<{
+    indent: OptionType<StringType>;
+    includeXmlDeclaration: BooleanType;
+    encodeEntities: BooleanType;
+    selfClosingTags: BooleanType;
+}>], BlobType>;
+/**
+ * Node.js implementation of XML platform functions.
+ *
+ * Pass this array to {@link East.compile} to enable XML operations.
+ */
+declare const XmlImpl: PlatformFunction[];
+/**
+ * Grouped XML platform functions.
+ *
+ * Provides XML parsing and serialization operations for East programs.
+ *
+ * @example
+ * ```ts
+ * import { East, BlobType } from "@elaraai/east";
+ * import { XML, XmlParseConfig, XmlNode } from "@elaraai/east-node-std";
+ *
+ * const parseXML = East.function([BlobType], XmlNode, ($, xmlBlob) => {
+ *     const config = $.const(East.value({
+ *         preserveWhitespace: false,
+ *         decodeEntities: true,
+ *     }, XmlParseConfig));
+ *
+ *     return XML.parse(xmlBlob, config);
+ * });
+ *
+ * const compiled = East.compile(parseXML.toIR(), XML.Implementation);
+ * const xmlData = new TextEncoder().encode("<book id='123'><title>East Guide</title></book>");
+ * compiled(xmlData);  // Returns parsed XML tree
+ * ```
+ */
+export declare const XML: {
+    /**
+     * Parses XML data from a binary blob into a recursive tree structure.
+     *
+     * Converts XML-formatted binary data into an XmlNode recursive structure.
+     * Supports XML declarations, namespaces, CDATA, entity decoding, and comments.
+     *
+     * @param blob - The XML data as a binary blob (UTF-8 encoded)
+     * @param config - Parsing configuration
+     * @returns An XmlNode representing the root element
+     * @throws {EastError} When XML is malformed
+     *
+     * @example
+     * ```ts
+     * const parseXML = East.function([BlobType], XmlNode, ($, xmlBlob) => {
+     *     const config = $.const(East.value({
+     *         preserveWhitespace: false,
+     *         decodeEntities: true,
+     *     }, XmlParseConfig));
+     *
+     *     return XML.parse(xmlBlob, config);
+     * });
+     *
+     * const compiled = East.compile(parseXML.toIR(), XML.Implementation);
+     * const xmlData = new TextEncoder().encode("<book><title>East</title></book>");
+     * compiled(xmlData);  // Returns: { tag: "book", attributes: Map{}, children: [...] }
+     * ```
+     */
+    readonly parse: import("@elaraai/east").PlatformDefinition<[BlobType, StructType<{
+        preserveWhitespace: BooleanType;
+        decodeEntities: BooleanType;
+    }>], RecursiveType<StructType<{
+        tag: StringType;
+        attributes: DictType<StringType, StringType>;
+        children: ArrayType<VariantType<{
+            TEXT: StringType;
+            ELEMENT: import("@elaraai/east").RecursiveTypeMarker;
+        }>>;
+    }>>>;
+    /**
+     * Serializes a recursive XML tree structure into XML-formatted binary data.
+     *
+     * Converts an XmlNode recursive structure into XML-formatted binary data.
+     * Supports indentation, XML declarations, entity encoding, and self-closing tags.
+     *
+     * @param node - The XmlNode root element to serialize
+     * @param config - Serialization configuration
+     * @returns A binary blob containing the XML-formatted data
+     *
+     * @example
+     * ```ts
+     * const serializeXML = East.function([XmlNode], BlobType, ($, doc) => {
+     *     const config = $.const(East.value({
+     *         indent: variant('some', "  "),
+     *         includeXmlDeclaration: true,
+     *         encodeEntities: true,
+     *         selfClosingTags: true,
+     *     }, XmlSerializeConfig));
+     *
+     *     return XML.serialize(doc, config);
+     * });
+     *
+     * const compiled = East.compile(serializeXML.toIR(), XML.Implementation);
+     * const xmlNode = { tag: "book", attributes: new Map(), children: [] };
+     * compiled(xmlNode);  // Returns blob: "<?xml version=\"1.0\"?>\n<book/>"
+     * ```
+     */
+    readonly serialize: import("@elaraai/east").PlatformDefinition<[RecursiveType<StructType<{
+        tag: StringType;
+        attributes: DictType<StringType, StringType>;
+        children: ArrayType<VariantType<{
+            TEXT: StringType;
+            ELEMENT: import("@elaraai/east").RecursiveTypeMarker;
+        }>>;
+    }>>, StructType<{
+        indent: OptionType<StringType>;
+        includeXmlDeclaration: BooleanType;
+        encodeEntities: BooleanType;
+        selfClosingTags: BooleanType;
+    }>], BlobType>;
+    /**
+     * Node.js implementation of XML platform functions.
+     *
+     * Pass this to {@link East.compile} to enable XML operations.
+     */
+    readonly Implementation: PlatformFunction[];
+    /**
+     * Type definitions for XML operations.
+     */
+    readonly Types: {
+        /**
+         * XML parsing configuration type.
+         */
+        readonly ParseConfig: StructType<{
+            preserveWhitespace: BooleanType;
+            decodeEntities: BooleanType;
+        }>;
+        /**
+         * XML serialization configuration type.
+         */
+        readonly SerializeConfig: StructType<{
+            indent: OptionType<StringType>;
+            includeXmlDeclaration: BooleanType;
+            encodeEntities: BooleanType;
+            selfClosingTags: BooleanType;
+        }>;
+        /**
+         * XML node recursive type (element with tag, attributes, and children).
+         */
+        readonly Node: RecursiveType<StructType<{
+            tag: StringType;
+            attributes: DictType<StringType, StringType>;
+            children: ArrayType<VariantType<{
+                TEXT: StringType;
+                ELEMENT: import("@elaraai/east").RecursiveTypeMarker;
+            }>>;
+        }>>;
+    };
+};
+export { XmlImpl };
+//# sourceMappingURL=xml.d.ts.map

package/dist/format/xml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xml.d.ts","sourceRoot":"","sources":["../../src/format/xml.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAQ,QAAQ,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAW,KAAK,WAAW,EAAa,MAAM,eAAe,CAAC;AACvL,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAK/D;;;;;GAKG;AACH,eAAO,MAAM,OAAO;;;;;;;GASnB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC,OAAO,OAAO,CAAC,CAAC;AAIvD,eAAO,MAAM,cAAc;;;EAGzB,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;EAK7B,CAAC;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;IAAkE,CAAC;AAEzF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;cAA0E,CAAC;AAErG;;;;GAIG;AACH,QAAA,MAAM,OAAO,EAAE,gBAAgB,EAwB9B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,GAAG;IACZ;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;;;;;;;;;;;;IAGH;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;;;;;;;;;;;;;;IAGH;;;;OAIG;;IAGH;;OAEG;;QAEC;;WAEG;;;;;QAGH;;WAEG;;;;;;;QAGH;;WAEG;;;;;;;;;;CAGD,CAAC;AAGX,OAAO,EAAE,OAAO,EAAE,CAAC"}