@cntwg/xml-lib-js 0.0.35 → 0.0.37-b

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+#### *v0.0.3x*
+
+Pre-release version.
+
+> - update `xmldoc-lib.md`;
+> - update dependency on `@ygracs/xml-js6` module to v0.0.6-b;
+> - update dependency on `@cntwg/file-helper` module to v0.0.3;
+> - update dependency on `@ygracs/bsfoc-lib-js` module to v0.3.3;
+
 #### *v0.0.35*
 
 Pre-release version.

package/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2019-2025 Yuri Grachev
+Copyright (c) 2019-2026 Yuri Grachev
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/doc/xmldoc-lib.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.41|
+>|***rev.*:**|0.1.43|
 >|:---|---:|
->|date:|2025-08-23|
+>|date:|2026-01-18|
 
 ## Introduction
 
@@ -20,9 +20,9 @@ This descriptor is an `object` that describes a status for an operation with som
 | `isERR` | `boolean` | no | a flag which indicates whether an error was happen |
 | `errCode` | `number` | yes | an error code |
 | `errEvent` | `string` | no | an error event identifier |
-| `errMsg` | `string` | no | an error message |
-| `source` | `string` | no | path to a file |
-| `content` | `any` | no | content |
+| `errMsg` | `string` | yes | an error message |
+| `source` | `string` | yes | path to a file |
+| `content` | `any` | yes | content |
 
 ## Module constants
 
@@ -702,7 +702,7 @@ If `object` parameter is not a type of `object` or not given a `TypeError` throw
 
 #### class methods (*special*)
 
-##### **init()** => `boolean`
+##### **init()** => `void`
 
 This method initializes an element with a default values.
 

package/index.d.ts

@@ -0,0 +1,40 @@
+import xObj = require("@ygracs/xobj-lib-js");
+import xmlHelper = require("./lib/xml-helper");
+import xmldoc = require("./lib/xmldoc-lib");
+
+import {
+  readAsTagName,
+  readAsAttrName,
+  readAsAttrValue,
+  valueToElementID,
+} from "./lib/xml-base";
+
+import {
+  XML_DEF_PARSE_OPTIONS,
+  XML_DEF_ROOT_ETAG_NAME, XML_LANG_ATTR_TNAME,
+  TXmlContentParseOptions,
+  TXmlAttributesMapper,
+  TXmlElementController, TXmlElementsListController,
+  TXmlContentDeclaration,
+  TXmlContentRootElement,
+  TXmlContentContainer,
+} from "./lib/xmldoc-lib";
+
+export {
+  xObj, xmlHelper, xmldoc as xmlDoc,
+  readAsTagName,
+  readAsAttrName,
+  readAsAttrValue,
+  valueToElementID,
+  XML_DEF_PARSE_OPTIONS,
+  XML_DEF_ROOT_ETAG_NAME, XML_LANG_ATTR_TNAME,
+  TXmlContentParseOptions,
+  TXmlAttributesMapper,
+  TXmlElementController, TXmlElementsListController,
+  TXmlContentDeclaration,
+  TXmlContentRootElement,
+  TXmlContentContainer,
+};
+
+import type { fsoDescr } from '@cntwg/file-helper';
+export type { fsoDescr };

package/index.js

@@ -7,6 +7,11 @@ const xmldoc = require('./lib/xmldoc-lib');
 const xmlHelper = require('./lib/xml-helper');
 const xmlBase = require('./lib/xml-base');
 
+const {
+  // * import types definitions *
+  fsoDescr,
+} = require('@cntwg/file-helper');
+
 // === module inner block ===
 
 // === module main block ===
@@ -34,3 +39,7 @@ module.exports.TXmlElementsListController = xmldoc.TXmlElementsListController;
 module.exports.TXmlContentDeclaration = xmldoc.TXmlContentDeclaration;
 module.exports.TXmlContentRootElement = xmldoc.TXmlContentRootElement;
 module.exports.TXmlContentContainer = xmldoc.TXmlContentContainer;
+
+// * export types definitions *
+// @ts-ignore
+module.exports.fsoDescr = fsoDescr;

package/lib/xml-base.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Tries to convert a given value to a valid tag name of an XML-element.
+ * @since v0.0.28
+ */
+export function readAsTagName(value: any): string;
+/**
+ * Tries to convert a given value to a valid name of an XML-attribute.
+ * @since v0.0.28
+ */
+export function readAsAttrName(value: any): string;
+/**
+ * Tries to convert a given value to a valid "attribute value".
+ * @since v0.0.35
+ */
+export function readAsAttrValue(value: any): string | null;
+/**
+ * Tries to convert a given value to a valid identifier
+ * suitable as a value for an "ID-attribute" of an XML-element.
+ * @since v0.0.28
+ * @see valueToIDString
+ */
+export function valueToElementID(value: any): string;

package/lib/xml-helper.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Tries to get a child element.
+ */
+export function getChildByPath(obj: TXmlElementController, chain: string[]): TXmlElementController | null;
+/**
+ * Tries to get a child element.
+ */
+export function addChildByPath(obj: TXmlElementController, chain: string[]): TXmlElementController | null;
+/**
+ * Reads a text values from a given XML-element.
+ */
+export function extractTextValues(obj: TXmlElementController | TXmlElementsListController): string[];
+/**
+ * Reads a text values with a `lang` attribute from a given XML-element.
+ */
+export function extractTextValuesLn(obj: TXmlElementController | TXmlElementsListController): any[];
+import { TXmlElementController } from "./xmldoc-lib";
+import { TXmlElementsListController } from "./xmldoc-lib";

package/lib/xmldoc-lib.d.ts

@@ -0,0 +1,483 @@
+import {
+    DEF_XML_PARSE_OPTIONS,
+} from "@ygracs/xobj-lib-js";
+/**
+ * An XML-element controller settings.
+ */
+export type OPT_xmlelemsett = {
+    /**
+     * - parser options
+     */
+    parseOptions?: InstanceType<typeof TXmlContentParseOptions>;
+    /**
+     * - mode flag
+     */
+    proxyModeEnable?: boolean;
+    /**
+     * - <reserved>
+     */
+    isNullItemsAllowed?: boolean;
+};
+/**
+ * An XML-element controller configuration.
+ */
+export type XMLElementConfig = {
+    /**
+     * - parser options
+     */
+    parseOptions: InstanceType<typeof TXmlContentParseOptions>;
+    /**
+     * - mode flag
+     */
+    proxyModeEnable?: boolean;
+    /**
+     * - <reserved>
+     */
+    isNullItemsAllowed?: boolean;
+};
+/**
+ * An XML-content container settings.
+ */
+export type OPT_xmlcontsett = {
+    /**
+     * - parser options
+     */
+    parseOptions?: InstanceType<typeof TXmlContentParseOptions>;
+    /**
+     * - mode flag
+     */
+    proxyModeEnable?: boolean;
+    /**
+     * - <reserved>
+     */
+    isNullItemsAllowed?: boolean;
+    /**
+     * - tag name of the root element
+     */
+    rootETagName?: string;
+    /**
+     * - mode flag
+     */
+    autoBindRoot?: boolean;
+};
+/**
+ * An XML-content container settings.
+ */
+export type XMLContainerSettings = {
+    /**
+     * - parser options
+     */
+    parseOptions: InstanceType<typeof TXmlContentParseOptions>;
+    /**
+     * - mode flag
+     */
+    proxyModeEnable?: boolean;
+    /**
+     * - <reserved>
+     */
+    isNullItemsAllowed?: boolean;
+    /**
+     * - tag name of the root element
+     */
+    rootETagName: string;
+    /**
+     * - mode flag
+     */
+    autoBindRoot?: boolean;
+};
+
+export const XML_DEF_PARSE_OPTIONS: typeof DEF_XML_PARSE_OPTIONS;
+export const XML_DEF_ROOT_ETAG_NAME: "root";
+export const XML_LANG_ATTR_TNAME: "lang";
+
+/**
+ * Settings for the list load ops
+ */
+export type OPT_ELC_loaditems = {
+    /** - indicates whether to clear the list before load */
+    useClear?: boolean;
+}
+
+/**
+ * @classdesc This class implements an attributes mapper instance
+ */
+export class TXmlAttributesMapper {
+    /**
+     * Creates an attributes mapper instance
+     * @throws {TypeError}
+     */
+    constructor(obj: object, opt?: OPT_xmlelemsett);
+    /**
+     * Contains a list of all instance attributes as a `<name>-<value>` pairs
+     */
+    get entries(): string[][];
+    /**
+     * Checks whether an attribute exists.
+     */
+    hasAttribute(name: string): boolean;
+    /**
+     * Returns an attribute value.
+     */
+    getAttribute(name: string): string;
+    /**
+     * Sets an attribute value.
+     */
+    setAttribute(name: string, value: any): boolean;
+    /**
+     * Deletes an attribute.
+     */
+    delAttribute(name: string): boolean;
+    /**
+     * Renames an attribute.
+     * @since v0.0.30
+     */
+    renameAttribute(name: string, value: string): boolean;
+    /**
+     * Deletes all attributes.
+     */
+    clear(): void;
+    #private;
+}
+
+/**
+ * @classdesc This class implements an instance of an element controller
+ */
+export class TXmlElementController {
+    /**
+     * Tries to unwraps a given object.
+     */
+    protected static __unwrap(item: object): object | null;
+    /**
+     * Returns a child element.
+     * @since v0.0.31
+     */
+    protected static __getChildRaw(node: TXmlElementController, name: string): any | null;
+    /**
+     * Adds a new child element.
+     * @since v0.0.31
+     */
+    protected static __addChildRaw(node: TXmlElementController, name: string): any | null;
+    /**
+     * Sets a child element.
+     */
+    protected static __setChildRaw(node: TXmlElementController, name: string, obj: object): boolean;
+    /**
+     * Tries to clean a given object.
+     */
+    static clear(obj: object): void;
+    /**
+     * Creates new controller element.
+     * @since v0.0.30
+     */
+    static create(obj: object, opt?: object): TXmlElementController | TXmlElementsListController | null;
+    /**
+     * Creates an instance of an element controller
+     * @throws {TypeError}
+     */
+    constructor(obj: object, opt?: OPT_xmlelemsett);
+    /**
+     * Contains an element attribute mapper instance
+     */
+    get attributes(): TXmlAttributesMapper;
+    /**
+     * @experimental
+     */
+    get name(): string;
+    /**
+     * Contains an element text value
+     */
+    get textValue(): string;
+    set textValue(value: string);
+    /**
+     * Checks whether an attribute exists.
+     * @see TXmlAttributesMapper.hasAttribute
+     */
+    hasAttribute(name: string): boolean;
+    /**
+     * Returns an attribute value.
+     * @see TXmlAttributesMapper.getAttribute
+     */
+    getAttribute(name: string): string;
+    /**
+     * Sets an attribute value.
+     * @see TXmlAttributesMapper.setAttribute
+     */
+    setAttribute(...args: [name: string, value: any]): boolean;
+    /**
+     * Deletes an attribute.
+     * @see TXmlAttributesMapper.delAttribute
+     */
+    delAttribute(name: string): boolean;
+    /**
+     * Renames an attribute.
+     * @since v0.0.30
+     * @see TXmlAttributesMapper.renameAttribute
+     */
+    renameAttribute(...args: [name: string, value: string]): boolean;
+    /**
+     * Returns a text value in format of a `[ <lang>, <text> ]` pair.
+     */
+    getTextValue(): string[];
+    /**
+     * Sets a text value.
+     */
+    setTextValue(value: string | string[]): boolean;
+    /**
+     * Checks whether an element has a child element.
+     */
+    hasChild(name: string): boolean;
+    /**
+     * Returns a child element.
+     */
+    getChild(name: string): TXmlElementController | TXmlElementsListController | null;
+    /**
+     * Adds a new child element.
+     */
+    addChild(name: string): TXmlElementController | null;
+    /**
+     * Deletes a child element.
+     */
+    delChild(name: string): boolean;
+    /**
+     * Deletes all child elements and attributes.
+     */
+    clear(): void;
+    /**
+     * Loads a element content from a string.
+     * @since v0.0.30
+     * @throws {Error}
+     * @experimental
+     */
+    loadFromXMLString(xmlString: string): boolean;
+    #private;
+}
+
+/**
+ * @classdesc This class implements an instance of a list controller
+ */
+export class TXmlElementsListController {
+    /**
+     * Returns an element.
+     * @since v0.0.34
+     */
+    protected static __getItemRaw(node: TXmlElementsListController, index: number | string): object | null;
+    /**
+     * Sets a new element.
+     * @since v0.0.34
+     */
+    protected static __setItemRaw(node: TXmlElementsListController, index: number | string, item: any): boolean;
+    /**
+     * Creates an instance of a list controller
+     * @throws {TypeError}
+     */
+    constructor(obj: object[], opt?: OPT_xmlelemsett);
+    /**
+     * Contains a quantity of an elements
+     */
+    get count(): number;
+    /**
+     * Contains a quantity of an elements
+     */
+    get size(): number;
+    /**
+     * Contains a maximum possible element index in the list
+     */
+    get maxIndex(): number;
+    /**
+     * Indicates whether a `null`-element is allowed
+     */
+    get isNullItemsAllowed(): boolean;
+    /**
+     * Deletes all child elements and attributes.
+     */
+    clear(): void;
+    /**
+     * Checks whether an instance holds none element.
+     */
+    isEmpty(): boolean;
+    /**
+     * Checks whether an instance holds at least one element.
+     */
+    isNotEmpty(): boolean;
+    /**
+     * Checks whether a given value is a valid index value
+     * and it is not exceeds an index range within the instance.
+     */
+    chkIndex(value: number | string): boolean;
+    /**
+     * Checks whether or not a given element is valid.
+     */
+    isValidItem(obj: any): boolean;
+    /**
+     * Returns an element.
+     * @deprecated
+     * @todo \[since `v0.0.34`] deprecated and will be removed later, consider
+     *    to use `TXmlElementsListController.__getItemRaw` instead.
+     */
+    protected _getItemRaw(index: number | string): object | null;
+    /**
+     * Returns an element.
+     */
+    getItem(index: number | string): TXmlElementController | null;
+    /**
+     * Adds a new element.
+     */
+    protected _addItemRaw(item: any): number;
+    /**
+     * Adds a new element.
+     */
+    addItem(item: any): number;
+    /**
+     * Sets a new element.
+     * @deprecated
+     * @todo \[since `v0.0.34`] deprecated and will be removed later, consider
+     *    to use `TXmlElementsListController.__setItemRaw` instead.
+     */
+    protected _setItemRaw(index: number | string, item: any): boolean;
+    /**
+     * Sets a new element.
+     */
+    setItem(index: number | string, item: any): boolean;
+    /**
+     * Insertes a new element.
+     */
+    protected _insItemRaw(index: number | string, item: any): boolean;
+    /**
+     * Insertes a new element.
+     */
+    insItem(index: number | string, item: any): boolean;
+    /**
+     * Deletes an element.
+     */
+    delItem(value: number | string): boolean;
+    /**
+     * Loads a list of an elements.
+     */
+    loadItems(items: any, opt?: OPT_ELC_loaditems): number;
+    [Symbol.iterator](): {
+        next: () => {
+            done: boolean;
+            value: TXmlElementController | null;
+        } | {
+            done: boolean;
+            value: undefined;
+        };
+        return(): {
+            done: boolean;
+            value: undefined;
+        };
+    };
+    #private;
+}
+
+import { TXmlContentParseOptions } from "@ygracs/xobj-lib-js";
+
+/**
+ * @classdesc This class implements an instance of an element
+ *            that managea content of a document declaration
+ */
+export class TXmlContentDeclaration {
+    /**
+     * Creates an instance of the element
+     * @throws {TypeError}
+     */
+    constructor(obj: object, opt?: OPT_xmlcontsett);
+    /**
+     * Contains a version of an XML
+     */
+    get version(): string;
+    set version(value: string);
+    /**
+     * Contains a document character set
+     */
+    get encoding(): string;
+    set encoding(value: string);
+    /**
+     * Initializes an instance content.
+     */
+    init(): void;
+    #private;
+}
+
+/**
+ * @augments TXmlElementController
+ * @classdesc This class implements an instance of a root element
+ */
+export class TXmlContentRootElement extends TXmlElementController {
+    /**
+     * Tries to unwraps a given object.
+     */
+    protected static __unwrap(item: object, opt?: boolean): object | null;
+    /**
+     * Creates an instance of a root element.
+     * @throws {TypeError}
+     */
+    constructor(obj: object, opt?: OPT_xmlcontsett);
+    /**
+     * @experimental
+     */
+    get tagName(): string;
+    set tagName(value: string);
+    #private;
+}
+
+/**
+ * @classdesc This class implements an instance of a container
+ *            that managea content of a document
+ */
+export class TXmlContentContainer {
+    /**
+     * Creates an instance of the container
+     */
+    constructor(opt?: OPT_xmlcontsett);
+    /**
+     * Returns a root element
+     */
+    get rootElement(): TXmlContentRootElement;
+    /**
+     * Cleans a document content.
+     */
+    clear(): void;
+    /**
+     * Initializes an instance with a given content.
+     */
+    protected _bindContent(obj: object, opt?: OPT_xmlcontsett): boolean;
+    /**
+     * Returns a document content as a string in an XML-format.
+     * @throws {Error}
+     */
+    saveToXMLString(): string;
+    /**
+     * Saves a document content to a file.
+     * @throws {Error}
+     */
+    saveToFile(source: string): Promise<fsoDescr>;
+    /**
+     * Saves a document content to a file.
+     */
+    saveToFileSync(source: string): fsoDescr;
+    /**
+     * Loads a document content from a string.
+     * @throws {Error}
+     */
+    loadFromXMLString(xmlString: string): boolean;
+    /**
+     * Loads a document content from a file.
+     * @throws {Error}
+     */
+    loadFromFile(source: string): Promise<fsoDescr>;
+    /**
+     * Loads a document content from a file.
+     * @throws {Error}
+     */
+    loadFromFileSync(source: string): fsoDescr;
+    /**
+     * Returns a document content a string in a JSON-format.
+     */
+    protected asJSON(): string;
+    #private;
+}
+
+import type { fsoDescr } from '@cntwg/file-helper';
+
+export { TXmlContentParseOptions };

package/lib/xmldoc-lib.js

@@ -1,4 +1,4 @@
-// [v0.2.118-20250823]
+// [v0.2.124-20260118]
 
 // === module init block ===
 
@@ -14,6 +14,9 @@ const {
 const {
   loadFromFileSync, loadFromFile,
   saveToFileSync, saveToFile,
+  // * import types definitions *
+  /** @see fsoDescr from `@cntwg/file-helper` */
+  fsoDescr,
 } = require('@cntwg/file-helper');
 
 const xObj = require('@ygracs/xobj-lib-js');
@@ -21,9 +24,11 @@ const {
   evalXObjEName,
   getXObjElement, addXObjElement, insertXObjElement,
   readXObjParam, writeXObjParam,
-  TXmlContentParseOptions,
+  //TXmlContentParseOptions,
   DEF_XML_PARSE_OPTIONS: XML_DEF_PARSE_OPTIONS,
 } = xObj;
+// keep the next line for a type checking work properly :(
+const { TXmlContentParseOptions } = require('@ygracs/xobj-lib-js/lib/xObj-defs');
 
 const {
   readAsTagName,
@@ -45,26 +50,37 @@ const {
  * @property {boolean} [isNullItemsAllowed=false] - <reserved>
  */
 
+/**
+ * An XML-element controller configuration.
+ * @typedef {Object} XMLElementConfig
+ * @property {TXmlContentParseOptions} parseOptions - parser options
+ * @property {boolean} [proxyModeEnable=false] - mode flag
+ * @property {boolean} [isNullItemsAllowed=false] - <reserved>
+ */
+
 /**
  * Evaluates an XML-element settings
  * @function __evalXMLElementSettings
- * @param {any} value - element settings to evaluate
- * @returns {OPT_xmlelemsett}
+ * @param {Object} value - element settings to evaluate
+ * @returns {XMLElementConfig}
  * @inner
  */
 function __evalXMLElementSettings(value) {
   /** @type {OPT_xmlelemsett} */
   const settings = isPlainObject(value) ? value : {};
   let {
+    parseOptions,
     proxyModeEnable,
     isNullItemsAllowed,
-    parseOptions,
   } = settings;
-  if (!(parseOptions instanceof TXmlContentParseOptions)) {
-    settings.parseOptions = new TXmlContentParseOptions(parseOptions);
-  };
+  settings.parseOptions = (
+    parseOptions instanceof TXmlContentParseOptions
+    ? parseOptions
+    : new TXmlContentParseOptions(parseOptions)
+  );
   if (typeof proxyModeEnable !== 'boolean') settings.proxyModeEnable = false;
   if (typeof isNullItemsAllowed !== 'boolean') settings.isNullItemsAllowed = false;
+  // @ts-expect-error
   return settings;
 };
 
@@ -79,11 +95,22 @@ function __evalXMLElementSettings(value) {
  * @see OPT_xmlelemsett
  */
 
+/**
+ * An XML-content container settings.
+ * @typedef {Object} XMLContainerSettings
+ * @property {TXmlContentParseOptions} parseOptions - parser options
+ * @property {boolean} [proxyModeEnable=false] - mode flag
+ * @property {boolean} [isNullItemsAllowed=false] - <reserved>
+ * @property {string} rootETagName - tag name of the root element
+ * @property {boolean} [autoBindRoot=true] - mode flag
+ * @see OPT_xmlelemsett
+ */
+
 /**
  * Evaluates an XML-container settings
  * @function __evalXMLContainerSettings
  * @param {any} value - container settings to evaluate
- * @returns {OPT_xmlcontsett}
+ * @returns {XMLContainerSettings}
  * @inner
  */
 function __evalXMLContainerSettings(value) {
@@ -98,6 +125,7 @@ function __evalXMLContainerSettings(value) {
   };
   settings.rootETagName = rootETagName;
   if (typeof autoBindRoot !== 'boolean') settings.autoBindRoot = true;
+  // @ts-expect-error
   return settings;
 };
 
@@ -129,8 +157,10 @@ const XML_TE_NROOT_EMSG = 'root element not found';
 class TXmlAttributesMapper {
   /** @type {object} */
   #_host;
-  /** @type {OPT_xmlelemsett} */
-  #_options;
+  ///** @type {OPT_xmlelemsett} */
+  //#_options;
+  /** @type {TXmlContentParseOptions} */
+  #_parseOptions;
 
   /**
    * Creates an attributes mapper instance
@@ -154,7 +184,7 @@ class TXmlAttributesMapper {
     };
     // save options
     settings.attributesKey = attributesKey;
-    this.#_options = parseOptions;
+    this.#_parseOptions = parseOptions;
   }
 
   /**
@@ -165,7 +195,7 @@ class TXmlAttributesMapper {
   get entries() {
     let items = xObj.getXObjAttributes(
       this.#_host,
-      this.#_options.settings.attributesKey,
+      this.#_parseOptions.settings.attributesKey,
     );
     return isPlainObject(items) ? Object.entries(items) : [];
   }
@@ -181,7 +211,7 @@ class TXmlAttributesMapper {
       result = xObj.checkXObjAttribute(
         this.#_host,
         name,
-        this.#_options.settings.attributesKey,
+        this.#_parseOptions.settings.attributesKey,
       );
     } catch (err) {
       // // TODO: verify what error is thrown
@@ -201,7 +231,7 @@ class TXmlAttributesMapper {
       result = xObj.readXObjAttr(
         this.#_host,
         name,
-        this.#_options.settings.attributesKey,
+        this.#_parseOptions.settings.attributesKey,
       );
     } catch (err) {
       // // TODO: verify what error is thrown
@@ -225,7 +255,7 @@ class TXmlAttributesMapper {
           this.#_host,
           name,
           value,
-          this.#_options.settings.attributesKey,
+          this.#_parseOptions.settings.attributesKey,
         );
       } catch (err) {
         // // TODO: verify what error is thrown
@@ -246,7 +276,7 @@ class TXmlAttributesMapper {
       result = xObj.deleteXObjAttribute(
         this.#_host,
         name,
-        this.#_options.settings.attributesKey,
+        this.#_parseOptions.settings.attributesKey,
       );
     } catch (err) {
       // // TODO: verify what error is thrown
@@ -271,7 +301,7 @@ class TXmlAttributesMapper {
           this.#_host,
           name,
           newName,
-          this.#_options.settings.attributesKey,
+          this.#_parseOptions.settings.attributesKey,
         );
       } catch (err) {
         // // TODO: verify what error is thrown
@@ -288,7 +318,7 @@ class TXmlAttributesMapper {
   clear() {
     insertXObjElement(
       this.#_host,
-      this.#_options.settings.attributesKey,
+      this.#_parseOptions.settings.attributesKey,
       {
         force: true,
         ripOldies: true,
@@ -304,9 +334,9 @@ class TXmlAttributesMapper {
 class TXmlElementController {
   /** @type {object} */
   #_host;
-  /** @type {OPT_xmlelemsett} */
+  /** @type {XMLElementConfig} */
   #_options;
-  /** @type {object} */
+  /** @type {TXmlContentParseOptions} */
   #_parseOptions;
   /** @type {TXmlAttributesMapper} */
   #_attributes;
@@ -593,11 +623,11 @@ class TXmlElementController {
         proxyModeEnable,
         parseOptions,
       } = _options;
-      parseOptions = parseOptions.xml2js;
-      parseOptions.ignoreDocType = true;
-      parseOptions.ignoreDeclaration = true;
+      const xml2jsOptions = parseOptions.xml2js;
+      xml2jsOptions.ignoreDocType = true;
+      xml2jsOptions.ignoreDeclaration = true;
       try {
-        let obj = xmlParser.xml2js(xmlString, parseOptions);
+        let obj = xmlParser.xml2js(xmlString, xml2jsOptions);
         if (isPlainObject(obj)) {
           let list = Object.entries(obj);
           let item = list[0];
@@ -761,7 +791,7 @@ class TXmlElementController {
 class TXmlElementsListController {
   /** @type {object[]} */
   #_host;
-  /** @type {OPT_xmlelemsett} */
+  /** @type {XMLElementConfig} */
   #_options;
   #_count = null;
 
@@ -1116,7 +1146,7 @@ class TXmlElementsListController {
 class TXmlContentDeclaration {
   /** @type {object} */
   #_host;
-  /** @type {OPT_xmlcontsett} */
+  /** @type {XMLContainerSettings} */
   #_options;
   /** @type {TXmlElementController} */
   #_ctrls;
@@ -1179,7 +1209,7 @@ class TXmlContentDeclaration {
 
   /**
    * Initializes an instance content.
-   * @returns {boolean}
+   * @returns {void}
    */
   init() {
     const _options = this.#_options;
@@ -1204,7 +1234,7 @@ class TXmlContentDeclaration {
 class TXmlContentRootElement extends TXmlElementController {
   /** @type {?object} */
   #_content;
-  /** @type {OPT_xmlcontsett} */
+  /** @type {XMLContainerSettings} */
   #_options;
 
   /**
@@ -1295,17 +1325,6 @@ class TXmlContentRootElement extends TXmlElementController {
 
 }
 
-/**
- * A fs ops description.
- * @typedef {Object} fsoDescr
- * @property {boolean} isERR - flag
- * @property {number} [errCode] - error code
- * @property {string} errEvent - event ID
- * @property {string} [errMsg] - event message
- * @property {string} [source] - path to file
- * @property {any} [content] - file content
- */
-
 /**
  * @classdesc This class implements an instance of a container
  *            that managea content of a document
@@ -1313,9 +1332,9 @@ class TXmlContentRootElement extends TXmlElementController {
 class TXmlContentContainer {
   /** @type {?object} */
   #_content;
-  /** @type {OPT_xmlcontsett} */
+  /** @type {XMLContainerSettings} */
   #_options;
-  /** @type {?object} */
+  /** @type {TXmlContentParseOptions} */
   #_parseOptions;
   /** @type {TXmlContentDeclaration} */
   #_docDecl;
@@ -1363,7 +1382,7 @@ class TXmlContentContainer {
   /**
    * Initializes an instance with a given content.
    * @param {object} obj
-   * @param {object} [opt]
+   * @param {OPT_xmlcontsett} [opt] - options
    * @returns {boolean}
    * @protected
    */
@@ -1590,8 +1609,3 @@ module.exports.TXmlContentParseOptions = TXmlContentParseOptions;
 module.exports.TXmlContentDeclaration = TXmlContentDeclaration;
 module.exports.TXmlContentRootElement = TXmlContentRootElement;
 module.exports.TXmlContentContainer = TXmlContentContainer;
-
-// * re-expected *
-module.exports.readAsTagName = readAsTagName;
-module.exports.readAsAttrName = readAsAttrName;
-module.exports.valueToElementID = valueToElementID;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cntwg/xml-lib-js",
-  "version": "0.0.35",
+  "version": "0.0.37-b",
   "description": "A library for handling an XML-documents",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -12,39 +12,38 @@
     "xml"
   ],
   "main": "./index.js",
+  "types": "./index.d.ts",
   "files": [
     "doc/xmldoc-lib.md",
     "lib/xmldoc-lib.js",
     "lib/xml-helper.js",
     "lib/xml-base.js",
+    "lib/*.d.ts",
     "index.js",
+    "index.d.ts",
     "CHANGELOG.md"
   ],
   "scripts": {
     "test": "jest",
-    "test-xml": "jest",
-    "test-xml:amap": "jest TXmlAttributesMapper",
-    "test-xml:ec": "jest TXmlElementController",
-    "test-xml:lc": "jest TXmlElementsListController",
-    "test-xml:re": "jest TXmlContentRootElement",
-    "test-xml:cdec": "jest TXmlContentDeclaration",
-    "test-xml:cc": "jest TXmlContentContainer",
     "build-doc-md": "jsdoc2md",
-    "build-doc-html": "jsdoc"
+    "build-doc-html": "jsdoc",
+    "gen-dts": "npx -p typescript tsc"
   },
   "imports": {
     "#lib/*": "./lib/*",
     "#test-dir/*": "./__test__/*"
   },
   "dependencies": {
-    "@cntwg/file-helper": "^0.0.1",
-    "@ygracs/bsfoc-lib-js": "^0.3.0",
-    "@ygracs/xml-js6": "^0.0.5-b",
-    "@ygracs/xobj-lib-js": "^0.2.4"
+    "@cntwg/file-helper": "^0.0.3",
+    "@ygracs/bsfoc-lib-js": "^0.3.3",
+    "@ygracs/xml-js6": "^0.0.6-b",
+    "@ygracs/xobj-lib-js": "^0.2.8-b"
   },
   "devDependencies": {
-    "jest": "^30.0.5",
-    "jsdoc-to-markdown": "^9.1.2",
-    "minimist": "^1.2.8"
+    "@ygracs/test-helper": "~0.0.1-b",
+    "jest": "^30.2.0",
+    "jsdoc-to-markdown": "^9.1.3",
+    "minimist": "^1.2.8",
+    "typescript": "~5.9.3"
   }
 }