@xapi-js/core/dist/index.d.cts

Core utilities and types for X-API.

/**
 * Represents the possible data types for X-API values.
 */
type XapiValueType = string | number | Uint8Array | Date | undefined;
/**
 * Represents a column within a row of an X-API dataset.
 */
interface Col {
    /** The ID of the column. */
    id: string;
    /** The value of the column. */
    value?: XapiValueType;
}
/**
 * Defines the possible types of rows in an X-API dataset (e.g., "insert", "update", "delete").
 */
declare const rowType: readonly ["insert", "update", "delete"];
/**
 * Type representing the operation performed on a row.
 */
type RowType = (typeof rowType)[number];
/**
 * Represents a row in an X-API dataset.
 */
interface Row {
    /** An array of columns in the row. */
    cols: Col[];
    /** An optional array of original columns for update/delete operations. */
    orgRow?: Col[];
    /** The type of operation for the row (e.g., "insert", "update", "delete"). */
    type?: RowType;
}
/**
 * Represents a collection of rows in an X-API dataset.
 */
interface Rows {
    /** An array of rows. */
    rows: Row[];
}
/**
 * Defines the possible data types for columns in an X-API dataset.
 */
declare const columnType: readonly ["STRING", "INT", "FLOAT", "DECIMAL", "BIGDECIMAL", "DATE", "DATETIME", "TIME", "BLOB"];
/**
 * Type representing the data type of a column.
 */
type ColumnType = (typeof columnType)[number];
/**
 * Represents a column definition in an X-API dataset.
 */
interface Column {
    /** The ID of the column. */
    id: string;
    /** The size of the column. */
    size: number;
    /** The data type of the column. */
    type: ColumnType;
}
/**
 * Represents a constant column definition, extending a regular column with a default value.
 */
type ConstColumn = Column & {
    value: XapiValueType;
};
/**
 * Represents the column information section of an X-API dataset.
 */
interface ColumnInfo {
    /** Optional array of constant column definitions. */
    constCols?: ConstColumn[];
    /** Optional array of regular column definitions. */
    cols?: Column[];
}
/**
 * Represents a parameter in an X-API request/response.
 */
interface Parameter {
    /** The ID of the parameter. */
    id: string;
    /** The data type of the parameter. */
    type?: ColumnType;
    /** The value of the parameter. */
    value?: XapiValueType;
}
/**
 * Represents a collection of parameters in an X-API request/response.
 */
interface XapiParameters {
    /** An array of parameters. */
    params: Parameter[];
}
/**
 * Defines the XML namespace and version for X-API.
 */
interface XapiVersion {
    /** The XML namespace URI. */
    xmlns: string;
    /** The version string. */
    version: string;
}
/**
 * Xplatform version definition for X-API XML.
 */
declare const XplatformVersion: {
    readonly xmlns: "http://www.tobesoft.com/platform/Dataset";
    readonly version: "4000";
};
/**
 * Nexacro version definition for X-API XML.
 */
declare const NexaVersion: {
    readonly xmlns: "http://www.nexacroplatform.com/platform/dataset";
    readonly version: "4000";
};
/**
 * Options for X-API processing.
 */
interface XapiOptions {
    /** The X-API version to use (e.g., XplatformVersion or NexaVersion). */
    xapiVersion?: typeof XplatformVersion | typeof NexaVersion;
    /** Whether to parse values to their specific types (true) or keep them as strings (false). */
    parseToTypes?: boolean;
}
/**
 * Custom error class for column type related issues.
 */
declare class ColumnTypeError extends Error {
    constructor(message: string);
}
declare class InvalidXmlError extends Error {
    constructor(message: string);
}

/**
 * Represents the root of an X-API XML structure, containing datasets and parameters.
 */
declare class XapiRoot {
    /** An array of datasets within the X-API root. */
    datasets: Dataset[];
    /** Parameters associated with the X-API root. */
    parameters: XapiParameters;
    /**
     * Creates an instance of XapiRoot.
     * @param datasets - Initial array of datasets.
     * @param parameters - Initial parameters.
     */
    constructor(datasets?: Dataset[], parameters?: XapiParameters);
    /**
     * Adds a dataset to the X-API root.
     * @param dataset - The dataset to add.
     */
    addDataset(dataset: Dataset): void;
    /**
     * Retrieves a dataset by its ID.
     * @param id - The ID of the dataset to retrieve.
     * @returns The Dataset object, or undefined if not found.
     */
    getDataset(id: string): Dataset | undefined;
    /**
     * Adds a parameter to the X-API root.
     * @param parameter - The parameter to add.
     */
    addParameter(parameter: Parameter): void;
    /**
     * Retrieves a parameter by its ID.
     * @param id - The ID of the parameter to retrieve.
     * @returns The Parameter object, or undefined if not found.
     */
    getParameter(id: string): Parameter | undefined;
    /**
     * Sets all parameters for the X-API root.
     * @param parameters - The XapiParameters object to set.
     */
    setParameters(parameters: XapiParameters): void;
    /**
     * Sets the value of a specific parameter, or adds it if it doesn't exist.
     * @param id - The ID of the parameter.
     * @param value - The value to set for the parameter.
     */
    setParameter(id: string, value: XapiValueType): void;
    /**
     * Returns the number of parameters.
     * @returns The count of parameters.
     */
    parameterSize(): number;
    /**
     * Returns the number of datasets.
     * @returns The count of datasets.
     */
    datasetSize(): number;
    /**
     * Iterates over the parameters.
     * @returns An IterableIterator for parameters.
     */
    iterParameters(): IterableIterator<Parameter>;
    /**
     * Iterates over the datasets.
     * @returns An IterableIterator for datasets.
     */
    iterDatasets(): IterableIterator<Dataset>;
}
/**
 * Represents a dataset within an X-API XML structure.
 */
declare class Dataset {
    /** The ID of the dataset. */
    id: string;
    private constColumns;
    private columns;
    /** An array of rows in the dataset. */
    rows: Row[];
    private _columnIndexMap;
    /**
     * Creates an instance of Dataset.
     * @param id - The ID of the dataset.
     * @param constColumns - Initial array of constant columns.
     * @param columns - Initial array of columns.
     * @param rows - Initial array of rows.
     */
    constructor(id: string, constColumns?: ConstColumn[], columns?: Column[], rows?: Row[]);
    /**
     * Adds a column definition to the dataset.
     * @param column - The column definition to add.
     */
    addColumn(column: Column): void;
    /**
     * Adds a constant column definition to the dataset.
     * @param column - The constant column definition to add.
     */
    addConstColumn(column: ConstColumn): void;
    /**
     * Creates a new empty row and adds it to the dataset.
     * @returns The index of the newly created row.
     */
    newRow(): number;
    /**
     * Adds an existing row to the dataset.
     * @param row - The row to add.
     */
    addRow(row: Row): void;
    /**
     * Retrieves the index of a column by its ID.
     * @param columnId - The ID of the column.
     * @returns The index of the column, or undefined if not found.
     */
    getColumnIndex(columnId: string): number | undefined;
    /**
     * Retrieves the column definition by its ID.
     * @param columnId - The ID of the column.
     * @returns The Column object, or undefined if not found.
     */
    getColumnInfo(columnId: string): Column | undefined;
    /**
     * Retrieves the constant column definition by its ID.
     * @param columnId - The ID of the constant column.
     * @returns The ConstColumn object, or undefined if not found.
     */
    getConstColumnInfo(columnId: string): ConstColumn | undefined;
    /**
     * Retrieves the value of a column in a specific row.
     * @param rowIdx - The index of the row.
     * @param columnId - The ID of the column.
     * @returns The value of the column, or undefined if the row or column is not found.
     * @throws {Error} if the column ID is not found in the dataset.
     */
    getColumn(rowIdx: number, columnId: string): XapiValueType | undefined;
    /**
     * Retrieves the original value of a column in a specific row (for OrgRow).
     * @param rowIdx - The index of the row.
     * @param columnId - The ID of the column.
     * @returns The original value of the column, or undefined if the row or column is not found.
     * @throws {Error} if the column ID is not found in the dataset.
     */
    getOrgColumn(rowIdx: number, columnId: string): XapiValueType | undefined;
    /**
     * Sets the value of a column in a specific row.
     * @param rowIdx - The index of the row.
     * @param columnId - The ID of the column.
     * @param value - The value to set.
     * @throws {Error} if the row index is out of bounds or the column ID is not found.
     */
    setColumn(rowIdx: number, columnId: string, value: XapiValueType): void;
    /**
     * Iterates over the constant column definitions.
     * @returns An IterableIterator for constant columns.
     */
    iterConstColumns(): IterableIterator<ConstColumn>;
    /**
     * Iterates over the column definitions.
     * @returns An IterableIterator for columns.
     */
    iterColumns(): IterableIterator<Column>;
    /**
     * Iterates over the rows in the dataset.
     * @returns An IterableIterator for rows.
     */
    iterRows(): IterableIterator<Row>;
    /**
     * Returns the number of column definitions.
     * @returns The count of columns.
     */
    columnSize(): number;
    /**
     * Returns the number of constant column definitions.
     * @returns The count of constant columns.
     */
    constColumnSize(): number;
    /**
     * Returns the number of rows in the dataset.
     * @returns The count of rows.
     */
    rowSize(): number;
}

/**
 * Initializes the X-API handler with the provided options.
 * @param options - The options to initialize the X-API handler.
 * @returns void
 */
declare function initXapi(options: XapiOptions): void;
/**
 * Parses an XML string into an XapiRoot object using txml.
 * @param xml - The string containing the XML data.
 * @returns A Promise that resolves to an XapiRoot object.
 */
declare function parse(xml: string): XapiRoot;
declare function writeString(root: XapiRoot): Promise<string>;
declare function write(stream: WritableStream<Uint8Array>, root: XapiRoot): Promise<void>;

declare function arrayBufferToString(buffer: ArrayBuffer): string;
/**
 * Creates an array of entities for parsing XML, including control characters.
 * @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.
 * @returns A Uint8Array.
 */
declare function base64ToUint8Array(base64String: string): Uint8Array;
/**
 * Converts a Uint8Array to a Base64 string.
 * @param uint8Array - The Uint8Array to convert.
 * @returns A Base64 string.
 */
declare function uint8ArrayToBase64(uint8Array: Uint8Array): string;
/**
 * Converts a string representation of a date/time to a Date object.
 * Supports "yyyyMMdd", "yyyyMMddHHmmss", "yyyyMMddHHmmssSSS", and "HHmmss" formats.
 * @param value - The string to convert.
 * @returns A Date object if the string is a valid date/time, otherwise undefined.
 */
declare function stringToDate(value: string): Date | undefined;
/**
 * Converts a Date object to a string representation based on the specified column type.
 * @param date - The Date object to convert.
 * @param type - The column type ("DATE", "DATETIME", or "TIME").
 * @returns A string representation of the date/time.
 */
declare function dateToString(date: Date, type: Extract<ColumnType, "DATE" | "DATETIME" | "TIME">): string;
/**
 * A WritableStream that collects all written Uint8Array chunks and provides them as a single string.
 */
declare class StringWritableStream extends WritableStream<Uint8Array> {
    private result;
    constructor();
    /**
     * Returns the collected string result.
     * @returns The concatenated string from all written chunks.
     */
    getResult(): string;
}
/**
 * Converts a string to a ReadableStream of Uint8Array.
 * @param str - The string to convert.
 * @returns A ReadableStream containing the string as Uint8Array.
 */
declare function stringToReadableStream(str: string): ReadableStream<Uint8Array>;
/**
 * Converts a value to the specified ColumnType.
 * @param value - The value to convert.
 * @param type - The target ColumnType.
 * @returns The converted value, or the original value if conversion fails or is not applicable.
 * @throws {ColumnTypeError} if the column type is unsupported.
 */
declare function convertToColumnType(value: XapiValueType, type: ColumnType): XapiValueType;
/**
 * Converts an XapiValueType to its string representation based on the specified ColumnType.
 * @param value - The value to convert.
 * @param type - The ColumnType to guide the conversion.
 * @returns The string representation of the value.
 */
declare function convertToString(value: XapiValueType, type: ColumnType): string;
declare function _unescapeXml(str?: string): string | undefined;

export { type Col, type Column, type ColumnInfo, type ColumnType, ColumnTypeError, type ConstColumn, Dataset, InvalidXmlError, NexaVersion, type Parameter, type Row, type RowType, type Rows, StringWritableStream, type XapiOptions, type XapiParameters, XapiRoot, type XapiValueType, type XapiVersion, XplatformVersion, _unescapeXml, arrayBufferToString, base64ToUint8Array, columnType, convertToColumnType, convertToString, dateToString, initXapi, makeParseEntities, makeWriterEntities, parse, rowType, stringToDate, stringToReadableStream, uint8ArrayToBase64, write, writeString };