@xapi-js/core 1.2.0 → 1.4.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,31 +322,32 @@ 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.
+ * @deprecated Use PARSE_ENTITIES directly for better performance
  * @returns An array of objects, each with an `entity` (e.g., "&#1;") and its `value` (e.g., "\x01").
  */
 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 +409,138 @@ 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
+//#region src/schema.d.ts
+type XapiTypeMap = {
+  STRING: string;
+  INT: number;
+  FLOAT: number;
+  DECIMAL: number;
+  BIGDECIMAL: number;
+  DATE: Date;
+  DATETIME: Date;
+  TIME: Date;
+  BLOB: Uint8Array;
+};
+interface XapiColumnSchema<T extends ColumnType = ColumnType, Optional extends boolean = boolean> {
+  readonly kind: "xapi-column";
+  readonly type: T;
+  readonly size: number;
+  readonly optional: Optional;
+}
+type XapiColumns = Record<string, XapiColumnSchema>;
+interface XapiDatasetSchema<Columns extends XapiColumns = XapiColumns> {
+  readonly kind: "xapi-dataset";
+  readonly columns: Columns;
+}
+type XapiDatasets = Record<string, XapiDatasetSchema>;
+interface XapiRootSchema<Datasets extends XapiDatasets = XapiDatasets, Parameters extends XapiColumns = XapiColumns> {
+  readonly kind: "xapi-root";
+  readonly datasets: Datasets;
+  readonly parameters: Parameters;
+}
+interface XapiOperation<Request extends XapiRootSchema = XapiRootSchema, Response extends XapiRootSchema = XapiRootSchema> {
+  readonly kind: "xapi-operation";
+  readonly request: Request;
+  readonly response: Response;
+}
+type RequiredColumnKeys<Columns extends XapiColumns> = { [Key in keyof Columns]-?: Columns[Key]["optional"] extends true ? never : Key; }[keyof Columns];
+type OptionalColumnKeys<Columns extends XapiColumns> = { [Key in keyof Columns]-?: Columns[Key]["optional"] extends true ? Key : never; }[keyof Columns];
+type InferColumns<Columns extends XapiColumns> = { [Key in RequiredColumnKeys<Columns>]: XapiTypeMap[Columns[Key]["type"]]; } & { [Key in OptionalColumnKeys<Columns>]?: XapiTypeMap[Columns[Key]["type"]]; };
+type InferDataset<Schema extends XapiDatasetSchema> = InferColumns<Schema["columns"]>[];
+type InferRoot<Schema extends XapiRootSchema> = {
+  parameters: InferColumns<Schema["parameters"]>;
+  datasets: { [Key in keyof Schema["datasets"]]: InferDataset<Schema["datasets"][Key]>; };
+};
+type RequestOf<Operation extends XapiOperation> = InferRoot<Operation["request"]>;
+type ResponseOf<Operation extends XapiOperation> = InferRoot<Operation["response"]>;
+type ColumnOptions<Optional extends boolean> = {
+  size?: number;
+  optional?: Optional;
+};
+declare function defineDataset<const Columns extends XapiColumns>(columns: Columns): XapiDatasetSchema<Columns>;
+declare function defineRoot<const Datasets extends XapiDatasets, const Parameters extends XapiColumns = Record<never, never>>(definition: {
+  datasets: Datasets;
+  parameters?: Parameters;
+}): XapiRootSchema<Datasets, Parameters>;
+declare function defineOperation<const Request extends XapiRootSchema, const Response extends XapiRootSchema>(definition: {
+  request: Request;
+  response: Response;
+}): XapiOperation<Request, Response>;
+declare const xapi: {
+  readonly string: <const Optional extends boolean = false>(options?: ColumnOptions<Optional>) => XapiColumnSchema<"STRING", Optional>;
+  readonly int: <const Optional extends boolean = false>(options?: ColumnOptions<Optional>) => XapiColumnSchema<"INT", Optional>;
+  readonly float: <const Optional extends boolean = false>(options?: ColumnOptions<Optional>) => XapiColumnSchema<"FLOAT", Optional>;
+  readonly decimal: <const Optional extends boolean = false>(options?: ColumnOptions<Optional>) => XapiColumnSchema<"DECIMAL", Optional>;
+  readonly bigdecimal: <const Optional extends boolean = false>(options?: ColumnOptions<Optional>) => XapiColumnSchema<"BIGDECIMAL", Optional>;
+  readonly date: <const Optional extends boolean = false>(options?: ColumnOptions<Optional>) => XapiColumnSchema<"DATE", Optional>;
+  readonly datetime: <const Optional extends boolean = false>(options?: ColumnOptions<Optional>) => XapiColumnSchema<"DATETIME", Optional>;
+  readonly time: <const Optional extends boolean = false>(options?: ColumnOptions<Optional>) => XapiColumnSchema<"TIME", Optional>;
+  readonly blob: <const Optional extends boolean = false>(options?: ColumnOptions<Optional>) => XapiColumnSchema<"BLOB", Optional>;
+  readonly dataset: typeof defineDataset;
+  readonly root: typeof defineRoot;
+  readonly operation: typeof defineOperation;
+};
+declare function encodeRoot<Schema extends XapiRootSchema>(schema: Schema, value: InferRoot<Schema>): XapiRoot;
+declare function decodeRoot<Schema extends XapiRootSchema>(schema: Schema, root: XapiRoot): InferRoot<Schema>;
 //#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, InferColumns, InferDataset, InferRoot, InvalidXmlError, NexaVersion, Parameter, RequestOf, ResponseOf, Row, RowType, Rows, StringWritableStream, XapiColumnSchema, XapiColumns, XapiDatasetSchema, XapiDatasets, XapiOperation, XapiOptions, XapiParameters, XapiRoot, XapiRootSchema, XapiTypeMap, XapiValueType, XapiVersion, XmlNode, XmlStringBuilder, XplatformVersion, _unescapeXml, arrayBufferToString, base64ToUint8Array, columnType, convertToColumnType, convertToString, dateToString, decodeRoot, defineDataset, defineOperation, defineRoot, encodeControlChars, encodeRoot, escapeXml, initXapi, isXapiRoot, makeParseEntities, parse, parseXml, rowType, stringToDate, stringToReadableStream, uint8ArrayToBase64, write, xapi };

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,31 +322,32 @@ 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.
+ * @deprecated Use PARSE_ENTITIES directly for better performance
  * @returns An array of objects, each with an `entity` (e.g., "&#1;") and its `value` (e.g., "\x01").
  */
 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 +409,138 @@ 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
+//#region src/schema.d.ts
+type XapiTypeMap = {
+  STRING: string;
+  INT: number;
+  FLOAT: number;
+  DECIMAL: number;
+  BIGDECIMAL: number;
+  DATE: Date;
+  DATETIME: Date;
+  TIME: Date;
+  BLOB: Uint8Array;
+};
+interface XapiColumnSchema<T extends ColumnType = ColumnType, Optional extends boolean = boolean> {
+  readonly kind: "xapi-column";
+  readonly type: T;
+  readonly size: number;
+  readonly optional: Optional;
+}
+type XapiColumns = Record<string, XapiColumnSchema>;
+interface XapiDatasetSchema<Columns extends XapiColumns = XapiColumns> {
+  readonly kind: "xapi-dataset";
+  readonly columns: Columns;
+}
+type XapiDatasets = Record<string, XapiDatasetSchema>;
+interface XapiRootSchema<Datasets extends XapiDatasets = XapiDatasets, Parameters extends XapiColumns = XapiColumns> {
+  readonly kind: "xapi-root";
+  readonly datasets: Datasets;
+  readonly parameters: Parameters;
+}
+interface XapiOperation<Request extends XapiRootSchema = XapiRootSchema, Response extends XapiRootSchema = XapiRootSchema> {
+  readonly kind: "xapi-operation";
+  readonly request: Request;
+  readonly response: Response;
+}
+type RequiredColumnKeys<Columns extends XapiColumns> = { [Key in keyof Columns]-?: Columns[Key]["optional"] extends true ? never : Key; }[keyof Columns];
+type OptionalColumnKeys<Columns extends XapiColumns> = { [Key in keyof Columns]-?: Columns[Key]["optional"] extends true ? Key : never; }[keyof Columns];
+type InferColumns<Columns extends XapiColumns> = { [Key in RequiredColumnKeys<Columns>]: XapiTypeMap[Columns[Key]["type"]]; } & { [Key in OptionalColumnKeys<Columns>]?: XapiTypeMap[Columns[Key]["type"]]; };
+type InferDataset<Schema extends XapiDatasetSchema> = InferColumns<Schema["columns"]>[];
+type InferRoot<Schema extends XapiRootSchema> = {
+  parameters: InferColumns<Schema["parameters"]>;
+  datasets: { [Key in keyof Schema["datasets"]]: InferDataset<Schema["datasets"][Key]>; };
+};
+type RequestOf<Operation extends XapiOperation> = InferRoot<Operation["request"]>;
+type ResponseOf<Operation extends XapiOperation> = InferRoot<Operation["response"]>;
+type ColumnOptions<Optional extends boolean> = {
+  size?: number;
+  optional?: Optional;
+};
+declare function defineDataset<const Columns extends XapiColumns>(columns: Columns): XapiDatasetSchema<Columns>;
+declare function defineRoot<const Datasets extends XapiDatasets, const Parameters extends XapiColumns = Record<never, never>>(definition: {
+  datasets: Datasets;
+  parameters?: Parameters;
+}): XapiRootSchema<Datasets, Parameters>;
+declare function defineOperation<const Request extends XapiRootSchema, const Response extends XapiRootSchema>(definition: {
+  request: Request;
+  response: Response;
+}): XapiOperation<Request, Response>;
+declare const xapi: {
+  readonly string: <const Optional extends boolean = false>(options?: ColumnOptions<Optional>) => XapiColumnSchema<"STRING", Optional>;
+  readonly int: <const Optional extends boolean = false>(options?: ColumnOptions<Optional>) => XapiColumnSchema<"INT", Optional>;
+  readonly float: <const Optional extends boolean = false>(options?: ColumnOptions<Optional>) => XapiColumnSchema<"FLOAT", Optional>;
+  readonly decimal: <const Optional extends boolean = false>(options?: ColumnOptions<Optional>) => XapiColumnSchema<"DECIMAL", Optional>;
+  readonly bigdecimal: <const Optional extends boolean = false>(options?: ColumnOptions<Optional>) => XapiColumnSchema<"BIGDECIMAL", Optional>;
+  readonly date: <const Optional extends boolean = false>(options?: ColumnOptions<Optional>) => XapiColumnSchema<"DATE", Optional>;
+  readonly datetime: <const Optional extends boolean = false>(options?: ColumnOptions<Optional>) => XapiColumnSchema<"DATETIME", Optional>;
+  readonly time: <const Optional extends boolean = false>(options?: ColumnOptions<Optional>) => XapiColumnSchema<"TIME", Optional>;
+  readonly blob: <const Optional extends boolean = false>(options?: ColumnOptions<Optional>) => XapiColumnSchema<"BLOB", Optional>;
+  readonly dataset: typeof defineDataset;
+  readonly root: typeof defineRoot;
+  readonly operation: typeof defineOperation;
+};
+declare function encodeRoot<Schema extends XapiRootSchema>(schema: Schema, value: InferRoot<Schema>): XapiRoot;
+declare function decodeRoot<Schema extends XapiRootSchema>(schema: Schema, root: XapiRoot): InferRoot<Schema>;
 //#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, InferColumns, InferDataset, InferRoot, InvalidXmlError, NexaVersion, Parameter, RequestOf, ResponseOf, Row, RowType, Rows, StringWritableStream, XapiColumnSchema, XapiColumns, XapiDatasetSchema, XapiDatasets, XapiOperation, XapiOptions, XapiParameters, XapiRoot, XapiRootSchema, XapiTypeMap, XapiValueType, XapiVersion, XmlNode, XmlStringBuilder, XplatformVersion, _unescapeXml, arrayBufferToString, base64ToUint8Array, columnType, convertToColumnType, convertToString, dateToString, decodeRoot, defineDataset, defineOperation, defineRoot, encodeControlChars, encodeRoot, escapeXml, initXapi, isXapiRoot, makeParseEntities, parse, parseXml, rowType, stringToDate, stringToReadableStream, uint8ArrayToBase64, write, xapi };