@ygracs/xobj-lib-js 0.2.3 → 0.2.5-b

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+#### *v0.2.x*
+
+Release version.
+
+> - update `xObj.md`;
+> - some fixes.
+
+#### *v0.2.4*
+
+Release version.
+
+> - updated dependency on `@ygracs/bsfoc-lib-js` module to v0.3.0.
+
 #### *v0.2.3*
 
 Release version.

package/doc/xObj.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.45|
+>|***rev.*:**|0.1.46|
 >|:---|---:|
->|date:|2025-07-19|
+>|date:|2025-12-14|
 
 ## Introduction
 
@@ -36,6 +36,58 @@ The behavior for `letterCase` settings defined in the table below:
 | `lower` | the resulting string must to be present in lower case |
 | any other values | the resulting string will be not transformed |
 
+<a name="typedef+xml2jsParseOptions"></a>
+#### `xml2jsParseOptions` - parser options set
+
+This options set is an `object` which defines how an 'XML'-string transforms into a 'JS'-object.
+
+| option name | value type | optional | description |
+|:---|---|---:|:---|
+| `compact` | `boolean` | `yes` ||
+| `declarationKey` | `string` | `yes` ||
+| `attributesKey` | `string` | `yes` ||
+| `textKey` | `string` | `yes` ||
+| `commentKey` | `string` | `yes` ||
+| `cdataKey` | `string` | `yes` ||
+| `nameKey` | `string` | `yes` ||
+| `typeKey` | `string` | `yes` ||
+| `parentKey` | `string` | `yes` ||
+| `elementsKey` | `string` | `yes` ||
+| `ignoreDeclaration` | `boolean` | `yes` ||
+| `ignoreDocType` | `boolean` | `yes` ||
+| `ignoreInstraction` | `boolean` | `yes` ||
+| `ignoreText` | `boolean` | `yes` ||
+| `ignoreComment` | `boolean` | `yes` ||
+| `ignoreCData` | `boolean` | `yes` ||
+| `addParent` | `boolean` | `yes` ||
+| `trim` | `boolean` | `yes` ||
+
+<a name="typedef+js2xmlParseOptions"></a>
+#### `js2xmlParseOptions` - parser options set
+
+This options set is an `object` which defines how a 'JS'-object transforms into an 'XML'-string.
+
+| option name | value type | optional | description |
+|:---|---|---:|:---|
+| `compact` | `boolean` | `yes` ||
+| `declarationKey` | `string` | `yes` ||
+| `attributesKey` | `string` | `yes` ||
+| `textKey` | `string` | `yes` ||
+| `commentKey` | `string` | `yes` ||
+| `cdataKey` | `string` | `yes` ||
+| `nameKey` | `string` | `yes` ||
+| `typeKey` | `string` | `yes` ||
+| `parentKey` | `string` | `yes` ||
+| `elementsKey` | `string` | `yes` ||
+| `ignoreDeclaration` | `boolean` | `yes` ||
+| `ignoreDocType` | `boolean` | `yes` ||
+| `ignoreInstraction` | `boolean` | `yes` ||
+| `ignoreText` | `boolean` | `yes` ||
+| `ignoreComment` | `boolean` | `yes` ||
+| `ignoreCData` | `boolean` | `yes` ||
+| `fullTagEmptyElement` | `boolean` | `yes` ||
+| `spaces` | `number` | `yes` ||
+
 ### Base constants
 
 |name|type|value|
@@ -50,28 +102,30 @@ This constant object provided by the module contains a default settings of optio
 
 The settings listed in the table below:
 
-|name|type|value|
-|:---|---|:---|
-|compact|`boolean`|`true`|
-|declarationKey|`string`|`__decl`|
-|attributesKey|`string`|`__attr`|
-|textKey|`string`|`__text`|
-|commentKey|`string`|`__note`|
-|cdataKey|`string`|`__cdata`|
-|nameKey|`string`|`__name`|
-|typeKey|`string`|`__type`|
-|parentKey|`string`|`parent`|
-|elementsKey|`string`|`items`|
-|ignoreDeclaration|`boolean`|`false`|
-|ignoreDocType|`boolean`|`false`|
-|ignoreInstractions|`boolean`|`false`|
-|ignoreText|`boolean`|`false`|
-|ignoreComments|`boolean`|`false`|
-|ignoreCData|`boolean`|`false`|
-|fullTagEmptyElement|`boolean`|`true`|
-|addParent|`boolean`|`false`|
-|trim|`boolean`|`true`|
-|spaces|`number`|`2`|
+| name | value type | value | description |
+|:---|---|---:|:---|
+| `compact` | `boolean` | `true` ||
+| `declarationKey` | `string` | `__decl` ||
+| `attributesKey` | `string` | `__attr` ||
+| `textKey` | `string` | `__text` ||
+| `commentKey` | `string` | `__note` ||
+| `cdataKey` | `string` | `__cdata` ||
+| `nameKey` | `string` | `__name` ||
+| `typeKey` | `string` | `__type` ||
+| `parentKey` | `string` | `parent` ||
+| `elementsKey` | `string` | `items` ||
+| `ignoreDeclaration` | `boolean` | `false` ||
+| `ignoreDocType` | `boolean` | `false` ||
+| `ignoreInstractions` | `boolean` | `false` | \<*deprecated*> (*use `ignoreInstraction` instead*) |
+| `ignoreInstraction` | `boolean` | `false` ||
+| `ignoreText` | `boolean` | `false` ||
+| `ignoreComments` | `boolean` | `false` | \<*deprecated*> (*use `ignoreComment` instead*) |
+| `ignoreComment` | `boolean` | `false` ||
+| `ignoreCData` | `boolean` | `false` ||
+| `fullTagEmptyElement` | `boolean` | `true` ||
+| `addParent` | `boolean` | `false` ||
+| `trim` | `boolean` | `true` ||
+| `spaces` | `number` | `2` ||
 
 ### Base functions for read an object parameter value
 
@@ -1176,14 +1230,14 @@ The class constructor receives an arguments listed below:
 
 | property type | read only | description |
 |---|---|:---|
-| `object` | yes | returns an options for an XML-to-JS converter |
+| `xml2jsParseOptions` | yes | returns an options for an XML-to-JS converter |
 
 <a name="TXmlContentParseOptions+js2xml"></a>
 ###### **js2xml**
 
 | property type | read only | description |
 |---|---|:---|
-| `object` | yes | returns an options for a JS-to-XML converter |
+| `js2xmlParseOptions` | yes | returns an options for a JS-to-XML converter |
 
 <a name="TXmlContentParseOptions+reservedKeys"></a>
 ###### **reservedKeys**

package/index.d.ts

@@ -0,0 +1,53 @@
+declare const _exports: {
+    readXObjParamRaw: typeof import("./lib/xObj-lib").readXObjParamRaw;
+    readXObjParam: typeof import("./lib/xObj-lib").readXObjParam;
+    readXObjParamAsBool: typeof import("./lib/xObj-lib").readXObjParamAsBool;
+    readXObjParamAsNum: typeof import("./lib/xObj-lib").readXObjParamAsNum;
+    readXObjParamEx: typeof import("./lib/xObj-lib").readXObjParamEx;
+    readXObjParamAsIndex: typeof import("./lib/xObj-lib").readXObjParamAsIndex;
+    writeXObjParamRaw: typeof import("./lib/xObj-lib").writeXObjParamRaw;
+    writeXObjParam: typeof import("./lib/xObj-lib").writeXObjParam;
+    writeXObjParamAsBool: typeof import("./lib/xObj-lib").writeXObjParamAsBool;
+    writeXObjParamAsNum: typeof import("./lib/xObj-lib").writeXObjParamAsNum;
+    writeXObjParamAsIndex: typeof import("./lib/xObj-lib").writeXObjParamAsIndex;
+    writeXObjParamEx: typeof import("./lib/xObj-lib").writeXObjParamEx;
+    readXObjAttrRaw: typeof import("./lib/xObj-lib").readXObjAttrRaw;
+    readXObjAttr: typeof import("./lib/xObj-lib").readXObjAttr;
+    readXObjAttrAsBool: typeof import("./lib/xObj-lib").readXObjAttrAsBool;
+    readXObjAttrAsNum: typeof import("./lib/xObj-lib").readXObjAttrAsNum;
+    readXObjAttrEx: typeof import("./lib/xObj-lib").readXObjAttrEx;
+    readXObjAttrAsIndex: typeof import("./lib/xObj-lib").readXObjAttrAsIndex;
+    writeXObjAttrRaw: typeof import("./lib/xObj-lib").writeXObjAttrRaw;
+    writeXObjAttr: typeof import("./lib/xObj-lib").writeXObjAttr;
+    writeXObjAttrAsBool: typeof import("./lib/xObj-lib").writeXObjAttrAsBool;
+    writeXObjAttrAsNum: typeof import("./lib/xObj-lib").writeXObjAttrAsNum;
+    writeXObjAttrAsIndex: typeof import("./lib/xObj-lib").writeXObjAttrAsIndex;
+    writeXObjAttrEx: typeof import("./lib/xObj-lib").writeXObjAttrEx;
+    getXObjAttributes: typeof import("./lib/xObj-lib").getXObjAttributes;
+    checkXObjAttribute: typeof import("./lib/xObj-lib").checkXObjAttribute;
+    deleteXObjAttribute: typeof import("./lib/xObj-lib").deleteXObjAttribute;
+    renameXObjAttribute: typeof import("./lib/xObj-lib").renameXObjAttribute;
+    getXObjElement: typeof import("./lib/xObj-lib").getXObjElement;
+    addXObjElement: typeof import("./lib/xObj-lib").addXObjElement;
+    insertXObjElement: typeof import("./lib/xObj-lib").insertXObjElement;
+    insertXObjElementEx: typeof import("./lib/xObj-lib").insertXObjElementEx;
+    deleteXObjElement: typeof import("./lib/xObj-lib").deleteXObjElement;
+    deleteXObjElementEx: typeof import("./lib/xObj-lib").deleteXObjElementEx;
+    renameXObjElement: typeof import("./lib/xObj-lib").renameXObjElement;
+    evalXObjEName: typeof import("./lib/xObj-lib").evalXObjEName;
+    insertXObjEList: typeof import("./lib/xObj-lib").insertXObjEList;
+    insertXObjEListEx: typeof import("./lib/xObj-lib").insertXObjEListEx;
+    evalKeyName: typeof import("./lib/xObj-lib").evalKeyName;
+    genXObjENameDescr: typeof import("./lib/xObj-lib").genXObjENameDescr;
+    insertXObjElements: typeof import("./lib/xObj-lib").insertXObjElements;
+    insertXObjEChain: typeof import("./lib/xObj-lib").insertXObjEChain;
+    readonly XOBJ_DEF_PARAM_TNAME: string;
+    readonly XOBJ_DEF_ATTR_TNAME: string;
+    TXmlContentParseOptions: typeof TXmlContentParseOptions;
+    DEF_XML_PARSE_OPTIONS: typeof DEF_XML_PARSE_OPTIONS;
+    XOBJ_DEF_TNAMES: typeof XOBJ_DEF_TNAMES;
+};
+export = _exports;
+import { TXmlContentParseOptions } from "./lib/xObj-defs";
+import { DEF_XML_PARSE_OPTIONS } from "./lib/xObj-defs";
+import { XOBJ_DEF_TNAMES } from "./lib/xObj-defs";

package/index.js

@@ -1,13 +1,14 @@
-// [v0.1.012-20240624]
+// [v0.1.013-20251213]
 
 // === module init block ===
 
 const {
   TXmlContentParseOptions,
   DEF_XML_PARSE_OPTIONS,
+  XOBJ_DEF_TNAMES,
 } = require('./lib/xObj-defs');
 
-// === module extra block (helper functions) ===
+// === module inner block ===
 
 // === module main block ===
 
@@ -16,3 +17,4 @@ const {
 module.exports = require('./lib/xObj-lib');
 module.exports.TXmlContentParseOptions = TXmlContentParseOptions;
 module.exports.DEF_XML_PARSE_OPTIONS = DEF_XML_PARSE_OPTIONS;
+module.exports.XOBJ_DEF_TNAMES = XOBJ_DEF_TNAMES;

package/lib/xObj-defs.d.ts

@@ -0,0 +1,166 @@
+/**
+ * A parser options settings
+ */
+export type OPT_parserOptions = {
+    compact?: boolean | undefined;
+    declarationKey?: string | undefined;
+    attributesKey?: string | undefined;
+    textKey?: string | undefined;
+    commentKey?: string | undefined;
+    cdataKey?: string | undefined;
+    nameKey?: string | undefined;
+    typeKey?: string | undefined;
+    parentKey?: string | undefined;
+    elementsKey?: string | undefined;
+    ignoreDeclaration?: boolean | undefined;
+    ignoreDocType?: boolean | undefined;
+    ignoreInstraction?: boolean | undefined;
+    ignoreText?: boolean | undefined;
+    ignoreComment?: boolean | undefined;
+    ignoreCData?: boolean | undefined;
+    fullTagEmptyElement?: boolean | undefined;
+    addParent?: boolean | undefined;
+    trim?: boolean | undefined;
+    spaces?: any;
+};
+/**
+ * A parser options to convert an 'XML'-string into a 'JS'-object
+ */
+export type xml2jsParseOptions = {
+    compact?: boolean | undefined;
+    declarationKey?: string | undefined;
+    attributesKey?: string | undefined;
+    textKey?: string | undefined;
+    commentKey?: string | undefined;
+    cdataKey?: string | undefined;
+    nameKey?: string | undefined;
+    typeKey?: string | undefined;
+    parentKey?: string | undefined;
+    elementsKey?: string | undefined;
+    ignoreDeclaration?: boolean | undefined;
+    ignoreDocType?: boolean | undefined;
+    ignoreInstraction?: boolean | undefined;
+    ignoreText?: boolean | undefined;
+    ignoreComment?: boolean | undefined;
+    ignoreCData?: boolean | undefined;
+    addParent?: boolean | undefined;
+    trim?: boolean | undefined;
+};
+/**
+ * A parser options to convert a 'JS'-object into an 'XML'-string
+ */
+export type js2xmlParseOptions = {
+    compact?: boolean | undefined;
+    declarationKey?: string | undefined;
+    attributesKey?: string | undefined;
+    textKey?: string | undefined;
+    commentKey?: string | undefined;
+    cdataKey?: string | undefined;
+    nameKey?: string | undefined;
+    typeKey?: string | undefined;
+    parentKey?: string | undefined;
+    elementsKey?: string | undefined;
+    ignoreDeclaration?: boolean | undefined;
+    ignoreDocType?: boolean | undefined;
+    ignoreInstraction?: boolean | undefined;
+    ignoreText?: boolean | undefined;
+    ignoreComment?: boolean | undefined;
+    ignoreCData?: boolean | undefined;
+    fullTagEmptyElement?: boolean | undefined;
+    spaces?: any;
+};
+export const XOBJ_DEF_PARAM_TNAME: "__text";
+export const XOBJ_DEF_ATTR_TNAME: "__attr";
+export namespace XOBJ_DEF_TNAMES {
+    export { XOBJ_DEF_PARAM_TNAME };
+    export { XOBJ_DEF_ATTR_TNAME };
+    export { XOBJ_DEF_DECL_TNAME };
+    export { XOBJ_DEF_CDATA_TNAME };
+}
+export namespace XOBJ_ECODE_TABLE {
+    export { XOBJ_TE_NOBJ_EMSG };
+    export { XOBJ_TE_NOBJ_ECODE };
+    export { XOBJ_TE_NARR_EMSG };
+    export { XOBJ_TE_NARR_ECODE };
+    export { XOBJ_TE_NSTR_EMSG };
+    export { XOBJ_TE_NSTR_ECODE };
+    export { XOBJ_TE_NPOBJ_EMSG };
+    export { XOBJ_TE_NPOBJ_ECODE };
+    export { XOBJ_TE_ANES_EMSG };
+    export { XOBJ_TE_ANES_ECODE };
+    export { XOBJ_TE_KNES_EMSG };
+    export { XOBJ_TE_KNES_ECODE };
+}
+export namespace DEF_XML_PARSE_OPTIONS {
+    export let compact: boolean;
+    export { XOBJ_DEF_DECL_TNAME as declarationKey };
+    export { XOBJ_DEF_ATTR_TNAME as attributesKey };
+    export { XOBJ_DEF_PARAM_TNAME as textKey };
+    export let commentKey: string;
+    export { XOBJ_DEF_CDATA_TNAME as cdataKey };
+    export let nameKey: string;
+    export let typeKey: string;
+    export let parentKey: string;
+    export let elementsKey: string;
+    export let ignoreDeclaration: boolean;
+    export let ignoreDocType: boolean;
+    /** @deprecated */
+    export let ignoreInstractions: boolean;
+    export let ignoreInstraction: boolean;
+    export let ignoreText: boolean;
+    /** @deprecated */
+    export let ignoreComments: boolean;
+    export let ignoreComment: boolean;
+    export let ignoreCData: boolean;
+    export let fullTagEmptyElement: boolean;
+    export let addParent: boolean;
+    export let trim: boolean;
+    export let spaces: number;
+}
+
+/**
+ * @classdesc Implements a container that provide a functionality to work
+ *    with options for an XML-parser
+ */
+export class TXmlContentParseOptions {
+    /**
+     * Creates a container instance
+     */
+    static createNewOptionsSet(opt?: any): OPT_parserOptions;
+    /**
+     * Creates a container instance
+     */
+    constructor(param?: any);
+    /**
+     * Contains a set of a current settings
+     */
+    get settings(): OPT_parserOptions;
+    /**
+     * Contains a set of a settings for converting an 'XML' to 'JS'-object
+     */
+    get xml2js(): xml2jsParseOptions;
+    /**
+     * Contains a set of a settings for converting an 'JS'-object to 'XML'
+     */
+    get js2xml(): js2xmlParseOptions;
+    /**
+     * Contains a set of a reserved key words
+     */
+    get reservedKeys(): Set<string>;
+    #private;
+}
+declare const XOBJ_DEF_DECL_TNAME: "__decl";
+declare const XOBJ_DEF_CDATA_TNAME: "__cdata";
+declare const XOBJ_TE_NOBJ_EMSG: "invalid argument (an object expected)";
+declare const XOBJ_TE_NOBJ_ECODE: "ERR_XOBJ_NOBJ";
+declare const XOBJ_TE_NARR_EMSG: "invalid argument (an array expected)";
+declare const XOBJ_TE_NARR_ECODE: "ERR_XOBJ_NARR";
+declare const XOBJ_TE_NSTR_EMSG: "invalid argument (a string expected)";
+declare const XOBJ_TE_NSTR_ECODE: "ERR_XOBJ_NSTR";
+declare const XOBJ_TE_NPOBJ_EMSG: "invalid argument (a plain object expected)";
+declare const XOBJ_TE_NPOBJ_ECODE: "ERR_XOBJ_NPOBJ";
+declare const XOBJ_TE_ANES_EMSG: "<attr_name> must be a non-empty string";
+declare const XOBJ_TE_ANES_ECODE: "ERR_XOBJ_INVARG_ATTR";
+declare const XOBJ_TE_KNES_EMSG: "<key_name> must be a non-empty string";
+declare const XOBJ_TE_KNES_ECODE: "ERR_XOBJ_INVARG_KEY";
+export {};

package/lib/xObj-defs.js

@@ -1,4 +1,4 @@
-// [v0.1.064-20250718]
+// [v0.1.067-20251214]
 
 // === module init block ===
 
@@ -6,7 +6,7 @@ const {
   isPlainObject,
 } = require('@ygracs/bsfoc-lib-js');
 
-// === module extra block (helper functions) ===
+// === module inner block ===
 
 // === module main block ===
 
@@ -16,6 +16,15 @@ const {
 
 const XOBJ_DEF_PARAM_TNAME = '__text';
 const XOBJ_DEF_ATTR_TNAME = '__attr';
+const XOBJ_DEF_DECL_TNAME = '__decl';
+const XOBJ_DEF_CDATA_TNAME = '__cdata';
+
+const XOBJ_DEF_TNAMES = {
+  XOBJ_DEF_PARAM_TNAME,
+  XOBJ_DEF_ATTR_TNAME,
+  XOBJ_DEF_DECL_TNAME,
+  XOBJ_DEF_CDATA_TNAME,
+};
 
 const XOBJ_TE_INVARG_EMSG = 'invalid argument';
 const XOBJ_TE_NOBJ_EMSG = `${XOBJ_TE_INVARG_EMSG} (an object expected)`;
@@ -46,22 +55,52 @@ const XOBJ_ECODE_TABLE = {
   XOBJ_TE_KNES_ECODE,
 };
 
+/**
+ * A parser options settings
+ * @typedef {Object} OPT_parserOptions
+ * @property {boolean} [compact]
+ * @property {string} [declarationKey]
+ * @property {string} [attributesKey]
+ * @property {string} [textKey]
+ * @property {string} [commentKey]
+ * @property {string} [cdataKey]
+ * @property {string} [nameKey]
+ * @property {string} [typeKey]
+ * @property {string} [parentKey]
+ * @property {string} [elementsKey]
+ * @property {boolean} [ignoreDeclaration]
+ * @property {boolean} [ignoreDocType]
+ * @property {boolean} [ignoreInstraction]
+ * @property {boolean} [ignoreText]
+ * @property {boolean} [ignoreComment]
+ * @property {boolean} [ignoreCData]
+ * @property {boolean} [fullTagEmptyElement]
+ * @property {boolean} [addParent]
+ * @property {boolean} [trim]
+ * @property {any} [spaces]
+ */
+
+/** @type {OPT_parserOptions} */
 const DEF_XML_PARSE_OPTIONS = {
   compact: true,
-  declarationKey: '__decl',
+  declarationKey: XOBJ_DEF_DECL_TNAME,
   attributesKey: XOBJ_DEF_ATTR_TNAME,
   textKey: XOBJ_DEF_PARAM_TNAME,
   commentKey: '__note',
-  cdataKey: '__cdata',
+  cdataKey: XOBJ_DEF_CDATA_TNAME,
   nameKey: '__name',
   typeKey: '__type',
   parentKey: 'parent',
   elementsKey: 'items',
   ignoreDeclaration: false,
   ignoreDocType: false,
+  /** @deprecated */
   ignoreInstractions: false,
+  ignoreInstraction: false,
   ignoreText: false,
+  /** @deprecated */
   ignoreComments: false,
+  ignoreComment: false,
   ignoreCData: false,
   fullTagEmptyElement: true,
   addParent: false,
@@ -77,13 +116,59 @@ const DEF_XML_PARSE_OPTIONS = {
  * (* class definitions *)
  */
 
+/**
+ * A parser options to convert an 'XML'-string into a 'JS'-object
+ * @typedef {Object} xml2jsParseOptions
+ * @property {boolean} [compact]
+ * @property {string} [declarationKey]
+ * @property {string} [attributesKey]
+ * @property {string} [textKey]
+ * @property {string} [commentKey]
+ * @property {string} [cdataKey]
+ * @property {string} [nameKey]
+ * @property {string} [typeKey]
+ * @property {string} [parentKey]
+ * @property {string} [elementsKey]
+ * @property {boolean} [ignoreDeclaration]
+ * @property {boolean} [ignoreDocType]
+ * @property {boolean} [ignoreInstraction]
+ * @property {boolean} [ignoreText]
+ * @property {boolean} [ignoreComment]
+ * @property {boolean} [ignoreCData]
+ * @property {boolean} [addParent]
+ * @property {boolean} [trim]
+ */
+
+/**
+ * A parser options to convert a 'JS'-object into an 'XML'-string
+ * @typedef {Object} js2xmlParseOptions
+ * @property {boolean} [compact]
+ * @property {string} [declarationKey]
+ * @property {string} [attributesKey]
+ * @property {string} [textKey]
+ * @property {string} [commentKey]
+ * @property {string} [cdataKey]
+ * @property {string} [nameKey]
+ * @property {string} [typeKey]
+ * @property {string} [parentKey]
+ * @property {string} [elementsKey]
+ * @property {boolean} [ignoreDeclaration]
+ * @property {boolean} [ignoreDocType]
+ * @property {boolean} [ignoreInstraction]
+ * @property {boolean} [ignoreText]
+ * @property {boolean} [ignoreComment]
+ * @property {boolean} [ignoreCData]
+ * @property {boolean} [fullTagEmptyElement]
+ * @property {any} [spaces]
+ */
+
 /**
  * @classdesc Implements a container that provide a functionality to work
  *    with options for an XML-parser
  */
 class TXmlContentParseOptions {
-  /** @type {object} */
-  #_options = null;
+  /** @type {OPT_parserOptions} */
+  #_options;
 
   /**
    * Creates a container instance
@@ -95,7 +180,7 @@ class TXmlContentParseOptions {
 
   /**
    * Contains a set of a current settings
-   * @type {object}
+   * @type {OPT_parserOptions}
    */
   get settings() {
     return this.#_options;
@@ -103,7 +188,7 @@ class TXmlContentParseOptions {
 
   /**
    * Contains a set of a settings for converting an 'XML' to 'JS'-object
-   * @type {object}
+   * @type {xml2jsParseOptions}
    */
   get xml2js() {
     let _settings = this.#_options;
@@ -120,9 +205,9 @@ class TXmlContentParseOptions {
       elementsKey: _settings.elementsKey,
       ignoreDeclaration: _settings.ignoreDeclaration,
       ignoreDocType: _settings.ignoreDocType,
-      ignoreInstraction: _settings.ignoreInstractions,
+      ignoreInstraction: _settings.ignoreInstraction,
       ignoreText: _settings.ignoreText,
-      ignoreComment: _settings.ignoreComments,
+      ignoreComment: _settings.ignoreComment,
       ignoreCData: _settings.ignoreCData,
       addParent: _settings.addParent,
       trim: _settings.trim,
@@ -131,7 +216,7 @@ class TXmlContentParseOptions {
 
   /**
    * Contains a set of a settings for converting an 'JS'-object to 'XML'
-   * @type {object}
+   * @type {js2xmlParseOptions}
    */
   get js2xml() {
     let _settings = this.#_options;
@@ -148,9 +233,9 @@ class TXmlContentParseOptions {
       elementsKey: _settings.elementsKey,
       ignoreDeclaration: _settings.ignoreDeclaration,
       ignoreDocType: _settings.ignoreDocType,
-      ignoreInstraction: _settings.ignoreInstractions,
+      ignoreInstraction: _settings.ignoreInstraction,
       ignoreText: _settings.ignoreText,
-      ignoreComment: _settings.ignoreComments,
+      ignoreComment: _settings.ignoreComment,
       ignoreCData: _settings.ignoreCData,
       fullTagEmptyElement: _settings.fullTagEmptyElement,
       spaces: _settings.spaces,
@@ -189,6 +274,7 @@ class TXmlContentParseOptions {
   /**
    * Creates a container instance
    * @param {any} [opt] - some initial options set
+   * @returns {OPT_parserOptions}
    * @static
    */
   static createNewOptionsSet(opt) {
@@ -212,9 +298,9 @@ class TXmlContentParseOptions {
       elementsKey: opt.elementsKey,
       ignoreDeclaration: opt.ignoreDeclaration,
       ignoreDocType: opt.ignoreDocType,
-      ignoreInstractions: opt.ignoreInstractions,
+      ignoreInstraction: opt.ignoreInstraction,
       ignoreText: opt.ignoreText,
-      ignoreComments: opt.ignoreComments,
+      ignoreComment: opt.ignoreComment,
       ignoreCData: opt.ignoreCData,
       fullTagEmptyElement: opt.fullTagEmptyElement,
       addParent: opt.addParent,
@@ -229,6 +315,7 @@ class TXmlContentParseOptions {
 
 module.exports.XOBJ_DEF_PARAM_TNAME = XOBJ_DEF_PARAM_TNAME;
 module.exports.XOBJ_DEF_ATTR_TNAME = XOBJ_DEF_ATTR_TNAME;
+module.exports.XOBJ_DEF_TNAMES = XOBJ_DEF_TNAMES;
 module.exports.XOBJ_ECODE_TABLE = XOBJ_ECODE_TABLE;
 module.exports.DEF_XML_PARSE_OPTIONS = DEF_XML_PARSE_OPTIONS;
 

package/lib/xObj-lib.d.ts

@@ -0,0 +1,301 @@
+/**
+ * A result of a value check ops.
+ */
+export type RVAL_reason = {
+    /**
+     * - message ID
+     */
+    code: string;
+    /**
+     * - message text
+     */
+    msg: string;
+};
+/**
+ * A result of a value check ops.
+ */
+export type VCOR_evalkname = {
+    /**
+     * - ops flag
+     */
+    isSucceed: boolean;
+    /**
+     * - result value or reson if failed
+     */
+    value: (string | RVAL_reason);
+};
+/**
+ * A result of an xObj modification ops
+ */
+export type RVAL_emodif = {
+    /**
+     * - flag that indicates whether an ops is succeed or not
+     */
+    isSucceed: boolean;
+    /**
+     * - some element as a result
+     */
+    item: (object | object[]) | null;
+};
+/**
+ * An options for an element insertion ops
+ */
+export type OPT_inselops_L = {
+    force?: boolean;
+    ripOldies?: boolean;
+    acceptIfList?: boolean;
+};
+/**
+ * An options for an element insertion ops
+ */
+export type OPT_inselops_S = {
+    force?: boolean;
+    ripOldies?: boolean;
+};
+
+export const XOBJ_DEF_PARAM_TNAME: string;
+export const XOBJ_DEF_ATTR_TNAME: string;
+
+/**
+ * Extracts a parameter 'AS IS' from a given object.
+ * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if third param is not a string
+ */
+export function readXObjParamRaw(obj: object, key?: string): any;
+/**
+ * Extracts a parameter from a given object and returns it as a string.
+ * @throws {TypeError} if first param is not an object
+ */
+export function readXObjParam(obj: object, key?: string): string;
+/**
+ * Extracts a parameter from a given object and returns it as a boolean.
+ * @throws {TypeError} if first param is not an object
+ */
+export function readXObjParamAsBool(obj: object, defValue?: boolean, key?: string): boolean;
+/**
+ * Extracts a parameter from a given object and returns it as a number.
+ * @throws {TypeError} if first param is not an object
+ */
+export function readXObjParamAsNum(obj: object, defValue?: number, key?: string): number;
+/**
+ * Extracts a parameter from a given object and returns it as a string.
+ * @throws {TypeError} if first param is not an object
+ * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
+ */
+export function readXObjParamEx(obj: object, opt?: object, key?: string): string;
+/**
+ * Extracts a parameter from a given object and returns it as 'index' value.
+ * @throws {TypeError} if first param is not an object
+ */
+export function readXObjParamAsIndex(obj: object, key?: string): number;
+/**
+ * Writes a parameter 'AS IS' into a given object.
+ * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if third param is not a string
+ */
+export function writeXObjParamRaw(obj: object, value: any, key?: string): boolean;
+/**
+ * Tries to convert a given value to a string and writes it as a parameter
+ * into a given object.
+ * @throws {TypeError} if first param is not an object
+ */
+export function writeXObjParam(obj: object, value: any, key?: string): boolean;
+/**
+ * Tries to convert a given value to a boolean and writes it as a parameter
+ * into a given object.
+ * @throws {TypeError} if first param is not an object
+ */
+export function writeXObjParamAsBool(obj: object, value: any, defValue?: boolean, key?: string): boolean;
+/**
+ * Tries to convert a given value to a number and writes it as a parameter
+ * into a given object.
+ * @throws {TypeError} if first param is not an object
+ */
+export function writeXObjParamAsNum(obj: object, value: any, defValue?: number, key?: string): boolean;
+/**
+ * Tries to convert a given value into an 'index' value and writes it
+ * as a parameter into a given object.
+ * @throws {TypeError} if first param is not an object
+ */
+export function writeXObjParamAsIndex(obj: object, value: any, key?: string): boolean;
+/**
+ * Tries to convert a given value to a string and writes it
+ * as a parameter into a given object.
+ * @throws {TypeError} if first param is not an object
+ * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
+ */
+export function writeXObjParamEx(obj: object, value: any, opt?: object, key?: string): boolean;
+/**
+ * Extracts an attribute 'AS IS' from a given object.
+ * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if third param is not a string
+ */
+export function readXObjAttrRaw(obj: object, attr?: string, key?: string): any;
+/**
+ * Extracts an attribute from a given object and returns it as a string.
+ * @throws {TypeError} if first param is not an object
+ */
+export function readXObjAttr(obj: object, attr: string, key?: string): string;
+/**
+ * Extracts an attribute from a given object and returns it as a boolean.
+ * @throws {TypeError} if first param is not an object
+ */
+export function readXObjAttrAsBool(obj: object, attr: string, defValue?: boolean, key?: string): boolean;
+/**
+ * Extracts an attribute from a given object and returns it as a number.
+ * @returns {number}
+ * @throws {TypeError} if first param is not an object
+ */
+export function readXObjAttrAsNum(obj: object, attr: string, defValue?: number, key?: string): number;
+/**
+ * Extracts an attribute from a given object and returns it as a string.
+ * @throws {TypeError} if first param is not an object
+ * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
+ */
+export function readXObjAttrEx(obj: object, attr: string, opt?: object, key?: string): string;
+/**
+ * Extracts an attribute from a given object and returns it as 'index' value.
+ * @throws {TypeError} if first param is not an object
+ */
+export function readXObjAttrAsIndex(obj: object, attr: string, key?: string): number;
+/**
+ * Writes a parameter into a given object.
+ * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if third param is not a string
+ */
+export function writeXObjAttrRaw(obj: object, attr: string, value: any, key?: string): boolean;
+/**
+ * Tries to convert a given value to a string and writes it as an attribute
+ * into a given object.
+ * @throws {TypeError} if first param is not an object
+ */
+export function writeXObjAttr(obj: object, attr: string, value: any, key?: string): boolean;
+/**
+ * Tries to convert a given value to a boolean and writes it as an attribute
+ * into a given object.
+ * @throws {TypeError} if first param is not an object
+ */
+export function writeXObjAttrAsBool(obj: object, attr: string, value: any, defValue?: boolean, key?: string): boolean;
+/**
+ * Tries to convert a given value to a number and writes it as an attribute
+ * into a given object.
+ * @throws {TypeError} if first param is not an object
+ */
+export function writeXObjAttrAsNum(obj: object, attr: string, value: any, defValue?: number, key?: string): boolean;
+/**
+ * Tries to convert a given value into an 'index' value and writes it
+ * as an attribute into a given object.
+ * @throws {TypeError} if first param is not an object
+ */
+export function writeXObjAttrAsIndex(obj: object, attr: string, value: any, key?: string): boolean;
+/**
+ * Tries to convert a given value to a string and writes it as an attribute
+ * into a given object.
+ * @throws {TypeError} if first param is not an object
+ * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
+ */
+export function writeXObjAttrEx(obj: object, attr: string, value: any, opt?: object, key?: string): boolean;
+/**
+ * Extracts an attributes from a given object by its key.
+ * @throws {TypeError} if first param is not an object
+ */
+export function getXObjAttributes(obj: object, key?: string): object | null;
+/**
+ * Checks whether an attribute is exists.
+ * @throws {TypeError} if first param is not an object
+ */
+export function checkXObjAttribute(obj: object, attr?: string, key?: string): boolean;
+/**
+ * Deletes an attribute addressed by a given name.
+ * @throws {TypeError} if first param is not an object
+ */
+export function deleteXObjAttribute(obj: object, attr?: string, key?: string): boolean;
+/**
+ * Renames an attribute addressed by a given name.
+ * @since 0.2.0
+ * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if second param is not an object
+ * @throws {TypeError} if third param is not an object
+ */
+export function renameXObjAttribute(obj: object, attr?: string, value?: string, key?: string): boolean;
+/**
+ * Extracts an element from a given object by its key.
+ * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if second param is empty string or not a string at all
+ */
+export function getXObjElement(obj: object, name: string): any | null;
+/**
+ * Adds an element addressed by its key to a given object.
+ * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if second param is empty string or not a string at all
+ */
+export function addXObjElement(obj: object, name: string): RVAL_emodif;
+/**
+ * Inserts an element addressed by its key into a given object.
+ * @throws {TypeError} if first param is not an object
+ * @see insertXObjElementEx
+ */
+export function insertXObjElement(...args: [obj: object, name: string, opt?: OPT_inselops_L]): object | null;
+/**
+ * Inserts an element addressed by its key into a given object.
+ * @since 0.2.0
+ * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if second param is empty string or not a string at all
+ */
+export function insertXObjElementEx(obj: object, name: string, opt?: OPT_inselops_L): RVAL_emodif;
+/**
+ * Deletes an element addressed by its key from a given object.
+ * @throws {TypeError} if first param is not an object
+ * @see deleteXObjElementEx
+ */
+export function deleteXObjElement(...args: [obj: object, name: string]): boolean;
+/**
+ * Deletes an element addressed by its key from a given object.
+ * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if second param is empty string or not a string at all
+ */
+export function deleteXObjElementEx(obj: object, name: string): RVAL_emodif;
+/**
+ * Renames an element addressed by its key.
+ * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if second param is not a string
+ * @throws {TypeError} if third param is not a string
+ */
+export function renameXObjElement(obj: object, name?: string, value?: string): boolean;
+
+/**
+ * Tries to convert a value into an ID.
+ */
+export function evalXObjEName(value: any): null | number | string;
+/**
+ * Inserts a list elements into a given object.
+ * @throws {TypeError} if first param is not an object
+ * @see insertXObjEListEx
+ */
+export function insertXObjEList(...args: [obj: object, name: string, opt?: OPT_inselops_S]): object | object[] | null;
+/**
+ * Inserts a list elements into a given object.
+ * @since 0.2.0
+ * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if second param is empty string or not a string at all
+ */
+export function insertXObjEListEx(obj: object, name: string, opt?: OPT_inselops_S): RVAL_emodif;
+/**
+ * Tries to convert a value into an ID.
+ * @inner
+ */
+export function evalKeyName(value: any, opt?: boolean): VCOR_evalkname;
+/**
+ * Tries to convert a value into an element name description.
+ */
+export function genXObjENameDescr(value: any): object;
+/**
+ * Inserts an elements into a given object.
+ * @throws {TypeError} if first param is not an object
+ */
+export function insertXObjElements(obj: object, ...args: any[]): number;
+/**
+ * Inserts a chain of an elements into a given object.
+ * @throws {TypeError} if first param is not an object
+ */
+export function insertXObjEChain(obj: object, ...args: any[]): any | null;

package/lib/xObj-lib.js

@@ -1,4 +1,4 @@
-// [v0.2.105-20250719]
+// [v0.2.106-20251213]
 
 // === module init block ===
 
@@ -10,6 +10,11 @@ const {
   isArray, isObject, isPlainObject,
 } = require('@ygracs/bsfoc-lib-js');
 
+const {
+  XOBJ_ECODE_TABLE,
+  XOBJ_DEF_TNAMES,
+} = require('./xObj-defs');
+
 const {
   XOBJ_TE_NSTR_EMSG,
   XOBJ_TE_NSTR_ECODE,
@@ -17,9 +22,14 @@ const {
   XOBJ_TE_NPOBJ_ECODE,
   XOBJ_TE_KNES_EMSG,
   XOBJ_TE_KNES_ECODE,
-} = require('#lib/xObj-defs.js').XOBJ_ECODE_TABLE;
+} = XOBJ_ECODE_TABLE;
 
-// === module extra block (helper functions) ===
+const {
+  XOBJ_DEF_PARAM_TNAME,
+  XOBJ_DEF_ATTR_TNAME,
+} = XOBJ_DEF_TNAMES;
+
+// === module inner block ===
 
 /**
  * A result of a value check ops.
@@ -75,9 +85,6 @@ function evalKeyName(value, opt = true) {
  * (* constant definitions *)
  */
 
-const XOBJ_DEF_PARAM_TNAME = '__text';
-const XOBJ_DEF_ATTR_TNAME = '__attr';
-
 /***
  * (* function definitions *)
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ygracs/xobj-lib-js",
-  "version": "0.2.3",
+  "version": "0.2.5-b",
   "description": "A helper library to work with xml-js module",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -9,28 +9,34 @@
     "url": "git+https://gitlab.com/ygracs/xobj-lib-js.git"
   },
   "main": "./index.js",
+  "types": "./index.d.ts",
   "files": [
     "doc/xObj.md",
     "lib/xObj-lib.js",
     "lib/xObj-defs.js",
+    "lib/*.d.ts",
     "index.js",
+    "index.d.ts",
     "CHANGELOG.md"
   ],
   "scripts": {
     "test": "jest",
     "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": {
-    "@ygracs/bsfoc-lib-js": "^0.2.3"
+    "@ygracs/bsfoc-lib-js": "^0.3.1-b"
   },
   "devDependencies": {
-    "jest": "^30.0.4",
-    "jsdoc-to-markdown": "^9.1.1",
-    "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"
   }
 }