@xapi-js/core 1.2.0 → 1.3.0

package/dist/index.d.cts

@@ -191,15 +191,15 @@ declare class XapiRoot {
    */
   datasetSize(): number;
   /**
-   * Iterates over the parameters.
-   * @returns An IterableIterator for parameters.
+   * Returns all parameters as an array.
+   * @returns An array of parameters.
    */
-  iterParameters(): IterableIterator<Parameter>;
+  getParameters(): Parameter[];
   /**
-   * Iterates over the datasets.
-   * @returns An IterableIterator for datasets.
+   * Returns all datasets as an array.
+   * @returns An array of datasets.
    */
-  iterDatasets(): IterableIterator<Dataset>;
+  getDatasets(): Dataset[];
 }
 /**
  * Represents a dataset within an X-API XML structure.
@@ -283,20 +283,20 @@ declare class Dataset {
    */
   setColumn(rowIdx: number, columnId: string, value: XapiValueType): void;
   /**
-   * Iterates over the constant column definitions.
-   * @returns An IterableIterator for constant columns.
+   * Returns all constant column definitions as an array.
+   * @returns An array of constant columns.
    */
-  iterConstColumns(): IterableIterator<ConstColumn>;
+  getConstColumns(): ConstColumn[];
   /**
-   * Iterates over the column definitions.
-   * @returns An IterableIterator for columns.
+   * Returns all column definitions as an array.
+   * @returns An array of columns.
    */
-  iterColumns(): IterableIterator<Column>;
+  getColumns(): Column[];
   /**
-   * Iterates over the rows in the dataset.
-   * @returns An IterableIterator for rows.
+   * Returns all rows in the dataset as an array.
+   * @returns An array of rows.
    */
-  iterRows(): IterableIterator<Row>;
+  getRows(): Row[];
   /**
    * Returns the number of column definitions.
    * @returns The count of columns.
@@ -322,14 +322,22 @@ declare class Dataset {
  */
 declare function initXapi(options: XapiOptions): void;
 /**
- * Parses an XML string into an XapiRoot object using txml.
+ * Parses an XML string into an XapiRoot object using custom parser.
  * @param xml - The string containing the XML data.
- * @returns A Promise that resolves to an XapiRoot object.
+ * @returns An XapiRoot object.
  */
 declare function parse(xml: string): XapiRoot;
 declare function write(root: XapiRoot): string;
 //#endregion
 //#region src/utils.d.ts
+/**
+ * Represents an XML node in the parsed structure.
+ */
+type XmlNode = {
+  tagName: string;
+  attributes?: Record<string, string>;
+  children?: (XmlNode | string)[];
+};
 declare function arrayBufferToString(buffer: ArrayBuffer): string;
 /**
  * Creates an array of entities for parsing XML, including control characters.
@@ -339,14 +347,6 @@ declare function makeParseEntities(): {
   entity: string;
   value: string;
 }[];
-/**
- * Creates an array of entities for writing XML, including control characters.
- * @returns An array of objects, each with an `entity` (e.g., "&#1;") and its `value` (e.g., "\x01").
- */
-declare function makeWriterEntities(): {
-  entity: string;
-  value: string;
-}[];
 /**
  * Converts a Base64 string to a Uint8Array.
  * @param base64String - The Base64 string to convert.
@@ -408,5 +408,64 @@ declare function convertToColumnType(value: XapiValueType, type: ColumnType): Xa
 declare function convertToString(value: XapiValueType, type: ColumnType): string;
 declare function _unescapeXml(str?: string): string | undefined;
 declare function isXapiRoot(value: unknown): value is XapiRoot;
+/**
+ * Escapes XML special characters in a string.
+ * @param str - The string to escape.
+ * @returns The escaped string.
+ */
+declare function escapeXml(str: string): string;
+/**
+ * Encodes control characters as XML entities, excluding standard whitespace.
+ * Encodes 0x01-0x08, 0x0B-0x0C, 0x0E-0x1F but NOT 0x09 (tab), 0x0A (LF), 0x0D (CR), 0x20 (space).
+ * @param str - The string to encode.
+ * @returns The encoded string.
+ */
+declare function encodeControlChars(str: string): string;
+/**
+ * A string builder for generating formatted XML.
+ */
+declare class XmlStringBuilder {
+  private lines;
+  private indentLevel;
+  private readonly indentString;
+  /**
+   * Writes the XML declaration.
+   * @param version - The XML version (default: "1.0").
+   * @param encoding - The encoding (default: "UTF-8").
+   */
+  writeDeclaration(version?: string, encoding?: string): void;
+  /**
+   * Writes a start element tag.
+   * @param name - The element name.
+   * @param attributes - Optional attributes object.
+   * @param selfClosing - Whether to create a self-closing tag.
+   */
+  writeStartElement(name: string, attributes?: Record<string, string>, selfClosing?: boolean): void;
+  /**
+   * Writes an end element tag.
+   * @param name - The element name.
+   */
+  writeEndElement(name: string): void;
+  /**
+   * Writes an element with text content.
+   * @param name - The element name.
+   * @param attributes - Optional attributes object.
+   * @param text - The text content.
+   */
+  writeElementWithText(name: string, attributes: Record<string, string> | undefined, text: string): void;
+  /**
+   * Returns the generated XML string.
+   * @returns The complete XML string with line breaks.
+   */
+  toString(): string;
+}
+/**
+ * Parses XML string into an XML node structure.
+ * This is a lightweight parser optimized for X-API XML structure.
+ *
+ * @param xml - The XML string to parse.
+ * @returns An array of parsed XML nodes.
+ */
+declare function parseXml(xml: string): XmlNode[];
 //#endregion
-export { Col, Column, ColumnInfo, ColumnType, ColumnTypeError, ConstColumn, Dataset, InvalidXmlError, NexaVersion, Parameter, Row, RowType, Rows, StringWritableStream, XapiOptions, XapiParameters, XapiRoot, XapiValueType, XapiVersion, XplatformVersion, _unescapeXml, arrayBufferToString, base64ToUint8Array, columnType, convertToColumnType, convertToString, dateToString, initXapi, isXapiRoot, makeParseEntities, makeWriterEntities, parse, rowType, stringToDate, stringToReadableStream, uint8ArrayToBase64, write };
+export { Col, Column, ColumnInfo, ColumnType, ColumnTypeError, ConstColumn, Dataset, InvalidXmlError, NexaVersion, Parameter, Row, RowType, Rows, StringWritableStream, XapiOptions, XapiParameters, XapiRoot, XapiValueType, XapiVersion, XmlNode, XmlStringBuilder, XplatformVersion, _unescapeXml, arrayBufferToString, base64ToUint8Array, columnType, convertToColumnType, convertToString, dateToString, encodeControlChars, escapeXml, initXapi, isXapiRoot, makeParseEntities, parse, parseXml, rowType, stringToDate, stringToReadableStream, uint8ArrayToBase64, write };

package/dist/index.d.ts

@@ -191,15 +191,15 @@ declare class XapiRoot {
    */
   datasetSize(): number;
   /**
-   * Iterates over the parameters.
-   * @returns An IterableIterator for parameters.
+   * Returns all parameters as an array.
+   * @returns An array of parameters.
    */
-  iterParameters(): IterableIterator<Parameter>;
+  getParameters(): Parameter[];
   /**
-   * Iterates over the datasets.
-   * @returns An IterableIterator for datasets.
+   * Returns all datasets as an array.
+   * @returns An array of datasets.
    */
-  iterDatasets(): IterableIterator<Dataset>;
+  getDatasets(): Dataset[];
 }
 /**
  * Represents a dataset within an X-API XML structure.
@@ -283,20 +283,20 @@ declare class Dataset {
    */
   setColumn(rowIdx: number, columnId: string, value: XapiValueType): void;
   /**
-   * Iterates over the constant column definitions.
-   * @returns An IterableIterator for constant columns.
+   * Returns all constant column definitions as an array.
+   * @returns An array of constant columns.
    */
-  iterConstColumns(): IterableIterator<ConstColumn>;
+  getConstColumns(): ConstColumn[];
   /**
-   * Iterates over the column definitions.
-   * @returns An IterableIterator for columns.
+   * Returns all column definitions as an array.
+   * @returns An array of columns.
    */
-  iterColumns(): IterableIterator<Column>;
+  getColumns(): Column[];
   /**
-   * Iterates over the rows in the dataset.
-   * @returns An IterableIterator for rows.
+   * Returns all rows in the dataset as an array.
+   * @returns An array of rows.
    */
-  iterRows(): IterableIterator<Row>;
+  getRows(): Row[];
   /**
    * Returns the number of column definitions.
    * @returns The count of columns.
@@ -322,14 +322,22 @@ declare class Dataset {
  */
 declare function initXapi(options: XapiOptions): void;
 /**
- * Parses an XML string into an XapiRoot object using txml.
+ * Parses an XML string into an XapiRoot object using custom parser.
  * @param xml - The string containing the XML data.
- * @returns A Promise that resolves to an XapiRoot object.
+ * @returns An XapiRoot object.
  */
 declare function parse(xml: string): XapiRoot;
 declare function write(root: XapiRoot): string;
 //#endregion
 //#region src/utils.d.ts
+/**
+ * Represents an XML node in the parsed structure.
+ */
+type XmlNode = {
+  tagName: string;
+  attributes?: Record<string, string>;
+  children?: (XmlNode | string)[];
+};
 declare function arrayBufferToString(buffer: ArrayBuffer): string;
 /**
  * Creates an array of entities for parsing XML, including control characters.
@@ -339,14 +347,6 @@ declare function makeParseEntities(): {
   entity: string;
   value: string;
 }[];
-/**
- * Creates an array of entities for writing XML, including control characters.
- * @returns An array of objects, each with an `entity` (e.g., "&#1;") and its `value` (e.g., "\x01").
- */
-declare function makeWriterEntities(): {
-  entity: string;
-  value: string;
-}[];
 /**
  * Converts a Base64 string to a Uint8Array.
  * @param base64String - The Base64 string to convert.
@@ -408,5 +408,64 @@ declare function convertToColumnType(value: XapiValueType, type: ColumnType): Xa
 declare function convertToString(value: XapiValueType, type: ColumnType): string;
 declare function _unescapeXml(str?: string): string | undefined;
 declare function isXapiRoot(value: unknown): value is XapiRoot;
+/**
+ * Escapes XML special characters in a string.
+ * @param str - The string to escape.
+ * @returns The escaped string.
+ */
+declare function escapeXml(str: string): string;
+/**
+ * Encodes control characters as XML entities, excluding standard whitespace.
+ * Encodes 0x01-0x08, 0x0B-0x0C, 0x0E-0x1F but NOT 0x09 (tab), 0x0A (LF), 0x0D (CR), 0x20 (space).
+ * @param str - The string to encode.
+ * @returns The encoded string.
+ */
+declare function encodeControlChars(str: string): string;
+/**
+ * A string builder for generating formatted XML.
+ */
+declare class XmlStringBuilder {
+  private lines;
+  private indentLevel;
+  private readonly indentString;
+  /**
+   * Writes the XML declaration.
+   * @param version - The XML version (default: "1.0").
+   * @param encoding - The encoding (default: "UTF-8").
+   */
+  writeDeclaration(version?: string, encoding?: string): void;
+  /**
+   * Writes a start element tag.
+   * @param name - The element name.
+   * @param attributes - Optional attributes object.
+   * @param selfClosing - Whether to create a self-closing tag.
+   */
+  writeStartElement(name: string, attributes?: Record<string, string>, selfClosing?: boolean): void;
+  /**
+   * Writes an end element tag.
+   * @param name - The element name.
+   */
+  writeEndElement(name: string): void;
+  /**
+   * Writes an element with text content.
+   * @param name - The element name.
+   * @param attributes - Optional attributes object.
+   * @param text - The text content.
+   */
+  writeElementWithText(name: string, attributes: Record<string, string> | undefined, text: string): void;
+  /**
+   * Returns the generated XML string.
+   * @returns The complete XML string with line breaks.
+   */
+  toString(): string;
+}
+/**
+ * Parses XML string into an XML node structure.
+ * This is a lightweight parser optimized for X-API XML structure.
+ *
+ * @param xml - The XML string to parse.
+ * @returns An array of parsed XML nodes.
+ */
+declare function parseXml(xml: string): XmlNode[];
 //#endregion
-export { Col, Column, ColumnInfo, ColumnType, ColumnTypeError, ConstColumn, Dataset, InvalidXmlError, NexaVersion, Parameter, Row, RowType, Rows, StringWritableStream, XapiOptions, XapiParameters, XapiRoot, XapiValueType, XapiVersion, XplatformVersion, _unescapeXml, arrayBufferToString, base64ToUint8Array, columnType, convertToColumnType, convertToString, dateToString, initXapi, isXapiRoot, makeParseEntities, makeWriterEntities, parse, rowType, stringToDate, stringToReadableStream, uint8ArrayToBase64, write };
+export { Col, Column, ColumnInfo, ColumnType, ColumnTypeError, ConstColumn, Dataset, InvalidXmlError, NexaVersion, Parameter, Row, RowType, Rows, StringWritableStream, XapiOptions, XapiParameters, XapiRoot, XapiValueType, XapiVersion, XmlNode, XmlStringBuilder, XplatformVersion, _unescapeXml, arrayBufferToString, base64ToUint8Array, columnType, convertToColumnType, convertToString, dateToString, encodeControlChars, escapeXml, initXapi, isXapiRoot, makeParseEntities, parse, parseXml, rowType, stringToDate, stringToReadableStream, uint8ArrayToBase64, write };