@ygracs/xobj-lib-js 0.3.2 → 0.4.0

package/lib/xObj-attr.js

@@ -1,4 +1,4 @@
-// [v0.3.138-20260530]
+// [v0.3.141-20260629]
 
 // === module init block ===
 
@@ -21,6 +21,9 @@ const {
 
 const {
   evalKeyName,
+} = require('./xObj-names');
+
+const {
   getXObjElement, insertXObjElement,
   // * import types definitions *
   INode,
@@ -44,7 +47,7 @@ const {
 /**
  * Extracts an attributes from a given object by its key.
  * @function getXObjAttributes
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} [key=XOBJ_DEF_ATTR_TNAME] - some key
  * @returns {?INode}
  * @throws {TypeError} if `obj` param is not an object
@@ -71,7 +74,7 @@ module.exports.getXObjAttributes = getXObjAttributes;
 /**
  * Checks whether an attribute is exists.
  * @function checkXObjAttribute
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute ID
  * @param {string} [key] - some key
  * @returns {boolean}
@@ -101,7 +104,7 @@ module.exports.checkXObjAttribute = checkXObjAttribute;
 /**
  * Deletes an attribute addressed by a given name.
  * @function deleteXObjAttribute
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute ID
  * @param {string} [key] - some key
  * @returns {boolean}
@@ -136,7 +139,7 @@ module.exports.deleteXObjAttribute = deleteXObjAttribute;
  * Renames an attribute addressed by a given name.
  * @since 0.2.0
  * @function renameXObjAttribute
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute ID
  * @param {string} value - new attribute ID
  * @param {string} [key] - some key
@@ -192,7 +195,7 @@ module.exports.renameXObjAttribute = renameXObjAttribute;
 /**
  * Extracts an attribute 'AS IS' from a given object.
  * @function readXObjAttrRaw
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute
  * @param {string} [key] - some key
  * @returns {any}
@@ -222,7 +225,7 @@ module.exports.readXObjAttrRaw = readXObjAttrRaw;
 /**
  * Writes a parameter into a given object.
  * @function writeXObjAttrRaw
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute
  * @param {any} value - some value
  * @param {string} [key=XOBJ_DEF_ATTR_TNAME] - some key
@@ -272,7 +275,7 @@ module.exports.writeXObjAttrRaw = writeXObjAttrRaw;
 /**
  * Extracts an attribute from a given object and returns it as a string.
  * @function readXObjAttr
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute
  * @param {string} [key] - some key
  * @returns {string}
@@ -298,7 +301,7 @@ module.exports.readXObjAttr = readXObjAttr;
 /**
  * Extracts an attribute from a given object and returns it as a boolean.
  * @function readXObjAttrAsBool
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute
  * @param {boolean} [defValue] - default value
  * @param {string} [key] - some key
@@ -327,7 +330,7 @@ module.exports.readXObjAttrAsBool = readXObjAttrAsBool;
 /**
  * Extracts an attribute from a given object and returns it as a number.
  * @function readXObjAttrAsNum
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute
  * @param {number} [defValue] - default value
  * @param {string} [key] - some key
@@ -356,7 +359,7 @@ module.exports.readXObjAttrAsNum = readXObjAttrAsNum;
 /**
  * Extracts an attribute from a given object and returns it as 'index' value.
  * @function readXObjAttrAsIndex
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute
  * @param {string} [key] - some key
  * @returns {number}
@@ -380,12 +383,24 @@ function readXObjAttrAsIndex(obj, attr, key) {
 };
 module.exports.readXObjAttrAsIndex = readXObjAttrAsIndex;
 
+/**
+ *
+ * @typedef {string} readXObjAttrOptionAsStr
+ * @deprecated
+ * @todo \[since `v0.2.1`] deprecated and will be removed
+ */
+/**
+ * A virtual constant meant for support jsdoc notation:
+ * @type {readXObjAttrOptionAsStr}
+ */
+module.exports.readXObjAttrOptionAsStr = '';
+
 /**
  * Extracts an attribute from a given object and returns it as a string.
  * @function readXObjAttrEx
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute
- * @param {object} [opt] - options
+ * @param {readXObjAttrOptionAsStr|IValueToStringTransformOptions} [opt] - options
  * @param {string} [key] - some key
  * @returns {string}
  * @throws {TypeError} if `obj` param is not an object
@@ -405,7 +420,6 @@ function readXObjAttrEx(obj, attr, opt, key) {
       }
     };
   };
-  /** @type {IValueToStringTransformOptions} */
   const _opt = isPlainObject(opt) ? opt : {
     useTrim: true,
     numberToString: true,
@@ -420,7 +434,7 @@ module.exports.readXObjAttrEx = readXObjAttrEx;
  * Tries to convert a given value to a string and writes it as an attribute
  * into a given object.
  * @function writeXObjAttr
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute
  * @param {any} value - some value
  * @param {string} [key] - some key
@@ -448,7 +462,7 @@ module.exports.writeXObjAttr = writeXObjAttr;
  * Tries to convert a given value to a boolean and writes it as an attribute
  * into a given object.
  * @function writeXObjAttrAsBool
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute
  * @param {any} value - some value
  * @param {boolean} [defValue] - default value
@@ -481,7 +495,7 @@ module.exports.writeXObjAttrAsBool = writeXObjAttrAsBool;
  * Tries to convert a given value to a number and writes it as an attribute
  * into a given object.
  * @function writeXObjAttrAsNum
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute
  * @param {any} value - some value
  * @param {number} [defValue] - default value
@@ -514,7 +528,7 @@ module.exports.writeXObjAttrAsNum = writeXObjAttrAsNum;
  * Tries to convert a given value into an 'index' value and writes it
  * as an attribute into a given object.
  * @function writeXObjAttrAsIndex
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute
  * @param {any} value - some value
  * @param {string} [key] - some key
@@ -542,14 +556,26 @@ function writeXObjAttrAsIndex(obj, attr, value, key) {
 };
 module.exports.writeXObjAttrAsIndex = writeXObjAttrAsIndex;
 
+/**
+ *
+ * @typedef {string} writeXObjAttrOptionAsStr
+ * @deprecated
+ * @todo \[since `v0.2.1`] deprecated and will be removed
+ */
+/**
+ * A virtual constant meant for support jsdoc notation:
+ * @type {writeXObjAttrOptionAsStr}
+ */
+module.exports.writeXObjAttrOptionAsStr = '';
+
 /**
  * Tries to convert a given value to a string and writes it as an attribute
  * into a given object.
  * @function writeXObjAttrEx
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} attr - some attribute
  * @param {any} value - some value
- * @param {object} [opt] - options
+ * @param {writeXObjAttrOptionAsStr|IValueToStringTransformOptions} [opt] - options
  * @param {string} [key] - some key
  * @returns {boolean}
  * @throws {TypeError} if `obj` param is not an object

package/lib/xObj-lib.d.ts

@@ -1,208 +1,114 @@
 /**
- * A result of `evalKeyName` function
+ * A `Node`-element
+ * @since 0.3.2
  */
-export type IEvalKeyNameResult = IEvalKeyNameResultOnSuccess | IEvalKeyNameResultOnFail;
-export const IEvalKeyNameResult: IEvalKeyNameResult;
 export type INode = {
     [x: string]: any;
 };
 export const INode: INode;
 /**
- * A result of an xObj modification ops
- */
-export type INodeModifResult = INodeModifResultOnFail | INodeModifResultOnSuccess;
-export const INodeModifResult: INodeModifResult;
-/**
- * Some conditions applied to an element as a result of an element name pattern
- * evaluation ops.
+ * A result of an xObj modification ops if failed
  */
-export type XObjENameDescrConditions = {
-    /**
-     * - element name
-     */
-    name: any;
+export type INodeModifResultOnFail = {
     /**
-     * - element type
+     * - flag that indicates whether an ops is succeed or not
      */
-    type: any;
+    isSucceed: false;
     /**
-     * - some value
+     * - some element as a result
      */
-    value?: any;
+    item: null;
 };
+export const INodeModifResultOnFail: INodeModifResultOnFail;
 /**
- * A result of an element name pattern evaluation ops.
+ * A result of an xObj modification ops if succeed (when child element returned)
  */
-export type XObjENameDescr = {
+export type INodeModifResultOnSuccess_S1 = {
     /**
-     * - ops flag
-     */
-    isERR: boolean;
-    /**
-     * - element name
+     * - flag that indicates whether an ops is succeed or not
      */
-    name: null | number | string;
+    isSucceed: true;
     /**
-     * - some conditions applied to an element
+     * - some element as a result
      */
-    conditions: XObjENameDescrConditions | null;
-};
-/**
- * A list of a `INode`-elements
- */
-export type INodeList = INode[];
-/**
- * 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;
+    item: INode;
 };
+export const INodeModifResultOnSuccess_S1: INodeModifResultOnSuccess_S1;
 /**
- * A result of a value check ops.
- * @deprecated
- * @todo \[from v0.3.0] make obsolete. Use `IEvalKeyNameReasonOnFail` instead.
+ * A result of an xObj modification ops if succeed (when child element returned)
  */
-export type RVAL_reason = {
+export type INodeModifResultOnSuccess_S2 = {
     /**
-     * - message ID
+     * - flag that indicates whether an ops is succeed or not
      */
-    code: string;
+    isSucceed: true;
     /**
-     * - message text
+     * - some element as a result
      */
-    msg: string;
+    item: INode[];
 };
+export const INodeModifResultOnSuccess_S2: INodeModifResultOnSuccess_S2;
 /**
- * An error description of a value check ops on fail.
+ * A result of an xObj modification ops if succeed (when child element not returned)
  */
-export type IEvalKeyNameReasonOnFail = {
+export type INodeModifResultOnSuccess_S0 = {
     /**
-     * - message ID
+     * - flag that indicates whether an ops is succeed or not
      */
-    code: string;
+    isSucceed: true;
     /**
-     * - message text
+     * - some element as a result
      */
-    msg: string;
+    item: null;
 };
+export const INodeModifResultOnSuccess_S0: INodeModifResultOnSuccess_S0;
 /**
- * A result of a value check ops.
- * @deprecated
- * @todo \[from v0.3.0] make obsolete. Use `IEvalKeyNameResult` instead.
+ * A list of a `Node`-elements
  */
-export type VCOR_evalkname = {
-    /**
-     * - ops flag
-     */
-    isSucceed: boolean;
-    /**
-     * - result value or reson if failed
-     */
-    value: string | IEvalKeyNameReasonOnFail;
-};
+export type INodeList = INode[];
 /**
- * An options setting for `evalKeyName` function
+ * A result of an xObj modification ops
+ * @since 0.4.0
  */
-export type IEvalKeyNameOptions = {
-    /**
-     * - a flag to accept only a non-empty string values
-     */
-    onlyNES?: boolean;
-};
+export type IAddNodeResult = INodeModifResultOnFail | INodeModifResultOnSuccess_S1;
 /**
- * A result of `evalKeyName` function if succeed
- */
-export type IEvalKeyNameResultOnSuccess = {
-    /**
-     * - ops flag
-     */
-    isSucceed: true;
-    /**
-     * - result value
-     */
-    value: string;
-};
-/**
- * A result of `evalKeyName` function if failed
+ * An options for an element insertion ops
  */
-export type IEvalKeyNameResultOnFail = {
-    /**
-     * - ops flag
-     */
-    isSucceed: false;
-    /**
-     * - reason of fail
-     */
-    value: IEvalKeyNameReasonOnFail;
+export type OPT_inselops_L = {
+    force?: boolean;
+    ripOldies?: boolean;
+    acceptIfList?: boolean;
 };
 /**
  * A result of an xObj modification ops
- * @deprecated
- * @todo \[from v0.3.2] make obsolete. Use `INodeModifResult` instead.
+ * @since 0.4.0
  */
-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;
-};
+export type IInsertNodeResult = INodeModifResultOnFail | INodeModifResultOnSuccess_S1 | INodeModifResultOnSuccess_S2;
 /**
- * A result of an xObj modification ops if failed
+ * A result of an xObj modification ops
+ * @since 0.4.0
  */
-export type INodeModifResultOnFail = {
-    /**
-     * - flag that indicates whether an ops is succeed or not
-     */
-    isSucceed: false;
-    /**
-     * - some element as a result
-     */
-    item: null;
-};
+export type IDeleteNodeResult = INodeModifResultOnFail | INodeModifResultOnSuccess_S0 | INodeModifResultOnSuccess_S1 | INodeModifResultOnSuccess_S2;
 /**
- * A result of an xObj modification ops if succeed
+ * An options for an element insertion ops
  */
-export type INodeModifResultOnSuccess = {
-    /**
-     * - flag that indicates whether an ops is succeed or not
-     */
-    isSucceed: true;
-    /**
-     * - some element as a result
-     */
-    item: object | object[];
+export type OPT_inselops_S = {
+    force?: boolean;
+    ripOldies?: boolean;
 };
 
-/**
- * Tries to convert a value into an ID.
- * @inner
- */
-export function evalKeyName(value: any, opt?: boolean | IEvalKeyNameOptions): IEvalKeyNameResult;
 /**
  * Extracts an element from a given object by its key.
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
-export function getXObjElement(obj: object, name: string): any | null;
+export function getXObjElement(obj: INode, name: string): any | null;
 /**
  * Adds an element addressed by its key to a given object.
  * @throws {TypeError} if `obj` param is not an object
  * @see {@link addXObjElementEx} for param details
  */
-export function addXObjElement(...args: addXObjElementParams): object | null;
+export function addXObjElement(...args: addXObjElementParams): INode | null;
 type addXObjElementParams = Parameters<typeof addXObjElementEx>;
 /**
  * Adds an element addressed by its key to a given object.
@@ -210,13 +116,13 @@ type addXObjElementParams = Parameters<typeof addXObjElementEx>;
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
-export function addXObjElementEx(obj: object, name: string): INodeModifResult;
+export function addXObjElementEx(obj: INode, name: string): IAddNodeResult;
 /**
  * Inserts an element addressed by its key into a given object.
  * @throws {TypeError} if `obj` param is not an object
  * @see {@link insertXObjElementEx} for param details
  */
-export function insertXObjElement(...args: insertXObjElementParams): object | null;
+export function insertXObjElement(...args: insertXObjElementParams): INode | INode[] | null;
 type insertXObjElementParams = Parameters<typeof insertXObjElementEx>;
 /**
  * Inserts an element addressed by its key into a given object.
@@ -224,7 +130,7 @@ type insertXObjElementParams = Parameters<typeof insertXObjElementEx>;
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
-export function insertXObjElementEx(obj: object, name: string, opt?: OPT_inselops_L): INodeModifResult;
+export function insertXObjElementEx(obj: INode, name: string, opt?: OPT_inselops_L): IInsertNodeResult;
 /**
  * Deletes an element addressed by its key from a given object.
  * @throws {TypeError} if `obj` param is not an object
@@ -237,29 +143,20 @@ type deleteXObjElementParams = Parameters<typeof deleteXObjElementEx>;
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
-export function deleteXObjElementEx(obj: object, name: string): INodeModifResult;
+export function deleteXObjElementEx(obj: INode, name: string): IDeleteNodeResult;
 /**
  * Renames an element addressed by its key.
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  * @throws {EvalKeyNameError} if `value` param is not valid identifier
  */
-export function renameXObjElement(obj: object, name?: string, value?: string): boolean;
-/**
- * Clears a given node
- * @throws {TypeError} if `node`-param is not an object or array
- */
-export function clearXObjNode(node: object | object[]): boolean;
-/**
- * Tries to convert a value into an ID.
- */
-export function evalXObjEName(value: any): null | number | string;
+export function renameXObjElement(obj: INode, name?: string, value?: string): boolean;
 /**
  * Inserts a list elements into a given object.
  * @throws {TypeError} if `obj` param is not an object
  * @see insertXObjEListEx
  */
-export function insertXObjEList(...args: insertXObjEListParams): object | object[] | null;
+export function insertXObjEList(...args: insertXObjEListParams): INode[] | null;
 type insertXObjEListParams = Parameters<typeof insertXObjEListEx>;
 /**
  * Inserts a list elements into a given object.
@@ -267,18 +164,22 @@ type insertXObjEListParams = Parameters<typeof insertXObjEListEx>;
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
-export function insertXObjEListEx(obj: object, name: string, opt?: OPT_inselops_S): INodeModifResult;
+export function insertXObjEListEx(obj: INode, name: string, opt?: OPT_inselops_S): INodeModifResultOnFail | INodeModifResultOnSuccess_S2;
 /**
- * Tries to convert a value into an element name description.
+ * Inserts a chain of an elements into a given object.
+ * @throws {TypeError} if `obj` param is not an object
+ * @experimental
  */
-export function genXObjENameDescr(value: any): XObjENameDescr;
+export function insertXObjEChain(obj: INode, ...args: insertListOfElementsParams): any | null;
 /**
- * Inserts an elements into a given object.
- * @throws {TypeError} if `obj` param is not an object
+ * Clears a given node
+ * @throws {TypeError} if `node`-param is not an object or array
  */
-export function insertXObjElements(obj: object, ...args: any[]): number;
+export function clearXObjNode(node: INode | INode[]): boolean;
 /**
- * Inserts a chain of an elements into a given object.
+ * Inserts an elements into a given object.
  * @throws {TypeError} if `obj` param is not an object
+ * @experimental
  */
-export function insertXObjEChain(obj: object, ...args: any[]): any | null;
+export function insertXObjElements(obj: INode, ...args: insertListOfElementsParams): number;
+type insertListOfElementsParams = [ ...names: string[], options: OPT_inselops_L];