@ygracs/xobj-lib-js 0.3.2 → 0.4.0

package/lib/xObj-lib.js

@@ -1,256 +1,34 @@
-// [v0.3.138-20260530]
+// [v0.3.144-20260704]
 
 // === module init block ===
 
 const {
-  valueToIndex,
-  readAsString, readAsBoolEx, readAsNumberEx,
   isNullOrUndef,
-  isInteger,
   isArray, isObject, isPlainObject,
-  // * import types definitions *
-  IValueToStringTransformOptions,
 } = require('@ygracs/bsfoc-lib-js');
 
+const {
+  evalKeyName,
+} = require('./xObj-names');
+
 const {
   EvalKeyNameError,
   XOBJ_ECODE_TABLE,
 } = require('./xObj-errors');
 
-const {
-  XOBJ_DEF_TNAMES,
-} = require('./xObj-defs');
-
 // === module inner block ===
 
 const {
-  XOBJ_TE_NSTR_EMSG,
   XOBJ_TE_NSTR_ECODE,
   XOBJ_TE_NPOBJ_EMSG,
   XOBJ_TE_NPOBJ_ECODE,
-  XOBJ_TE_KNES_EMSG,
   XOBJ_TE_KNES_ECODE,
 } = XOBJ_ECODE_TABLE;
 
-const {
-  XOBJ_DEF_PARAM_TNAME,
-} = XOBJ_DEF_TNAMES;
-
-/**
- * A result of a value check ops.
- * @typedef {Object} RVAL_reason
- * @property {string} code - message ID
- * @property {string} msg - message text
- * @deprecated
- * @todo \[from v0.3.0] make obsolete. Use `IEvalKeyNameReasonOnFail` instead.
- */
-
-/**
- * An error description of a value check ops on fail.
- * @since 0.3.0
- * @typedef {Object} IEvalKeyNameReasonOnFail
- * @property {string} code - message ID
- * @property {string} msg - message text
- */
-
-/**
- * A result of a value check ops.
- * @typedef {Object} VCOR_evalkname
- * @property {boolean} isSucceed - ops flag
- * @property {string|IEvalKeyNameReasonOnFail} value - result value or reson if failed
- * @deprecated
- * @todo \[from v0.3.0] make obsolete. Use `IEvalKeyNameResult` instead.
- */
-
-/**
- * An options setting for `evalKeyName` function
- * @since 0.3.0
- * @typedef {Object} IEvalKeyNameOptions
- * @property {boolean} [onlyNES] - a flag to accept only a non-empty string values
- */
-
-/**
- * A result of `evalKeyName` function if succeed
- * @since 0.3.0
- * @typedef {Object} IEvalKeyNameResultOnSuccess
- * @property {true} isSucceed - ops flag
- * @property {string} value - result value
- */
-
-/**
- * A result of `evalKeyName` function if failed
- * @since 0.3.0
- * @typedef {Object} IEvalKeyNameResultOnFail
- * @property {false} isSucceed - ops flag
- * @property {IEvalKeyNameReasonOnFail} value - reason of fail
- */
-
-/**
- * A result of `evalKeyName` function
- * @since 0.3.0
- * @typedef {IEvalKeyNameResultOnSuccess|IEvalKeyNameResultOnFail} IEvalKeyNameResult
- */
-/**
- * A virtual constant meant for support jsdoc notation:
- * @type {IEvalKeyNameResult}
- */
-module.exports.IEvalKeyNameResult = { isSucceed: true, value: '' };
-
-/**
- * Tries to convert a value into an ID.
- * @function evalKeyName
- * @param {any} value - key to validate
- * @param {boolean|IEvalKeyNameOptions} [opt=true] - some options
- * @returns {IEvalKeyNameResult}
- * @inner
- */
-function evalKeyName(value, opt = true) {
-  let {
-    onlyNES,
-  } = isPlainObject(opt) ? opt : { onlyNES: opt };
-  if (typeof value !== 'string') {
-    return {
-      isSucceed: false,
-      value: {
-        code: XOBJ_TE_NSTR_ECODE,
-        msg: XOBJ_TE_NSTR_EMSG,
-      },
-    };
-  };
-  const key = value.trim();
-  if (onlyNES && key === '') {
-    return {
-      isSucceed: false,
-      value: {
-        code: XOBJ_TE_KNES_ECODE,
-        msg: XOBJ_TE_KNES_EMSG,
-      },
-    };
-  };
-  return {
-    isSucceed: true,
-    value: key,
-  };
-};
-module.exports.evalKeyName = evalKeyName;
-
 // === module main block ===
 
 /**
- * Tries to convert a value into an ID.
- * @function evalXObjEName
- * @param {any} value - some value to evaluate
- * @returns {null|number|string}
- */
-function evalXObjEName(value) {
-  //return valueToIDString(value); // // TODO: [?]
-  let name = value;
-  switch (typeof name) {
-    case 'number' : {
-      if (valueToIndex(name) === -1) name = null;
-      break;
-    }
-    case 'string' : {
-      name = name.trim();
-      if (name !== '') {
-        let value = Number(name);
-        if (!Number.isNaN(value)) {
-          name = (
-            value < 0 || !isInteger(value)
-            ? null
-            : value
-          );
-        };
-      } else {
-        name = null;
-      };
-      break;
-    }
-    default: {
-      name = null;
-    }
-  };
-  return name;
-};
-
-/**
- * Some conditions applied to an element as a result of an element name pattern
- * evaluation ops.
- * @since 0.3.0
- * @typedef {Object} XObjENameDescrConditions
- * @property {any} name - element name
- * @property {any} type - element type
- * @property {any} [value] - some value
- */
-
-/**
- * A result of an element name pattern evaluation ops.
- * @typedef {Object} XObjENameDescr
- * @property {boolean} isERR - ops flag
- * @property {null|number|string} name - element name
- * @property {?XObjENameDescrConditions} conditions - some conditions applied to an element
- */
-
-/**
- * Tries to convert a value into an element name description.
- * @function genXObjENameDescr
- * @param {any} value - element name pattern
- * @returns {XObjENameDescr}
- * @experimental
- */
-function genXObjENameDescr(value) {
-  let result = null;
-  let name = null;
-  let conditions = null;
-  let isERR = false;
-  let tail = null;
-  if (typeof value === 'string') {
-    const re = /^\s*([^\[\]\s]+)?(\s*)(\[.*])?\s*$/;
-    tail = value.match(re);
-    //console.log('CHECK: '+JSON.stringify(tail, null, 2));
-    if (tail) {
-      if (tail[1]) {
-        name = tail[1];
-        if (name) {
-          if (tail[2] === '') {
-            if (tail[3]) {
-              const re = /\[(@{0,1})(?:([^\[=]*?)(?:(?=[=])(=)((?![\"\'])[^\]]*|(?=([\"\']))\5(.*)\5))?)](\s*.*)/;
-              tail = tail[3].match(re);
-              //console.log('CHECK: '+JSON.stringify(tail, null, 2));
-              if (tail) {
-                let name = evalXObjEName(tail[2]);
-                let type = tail[1] === '@' ? 'attribute' : 'child';
-                let value = undefined;
-                if (tail[3] === '=') value = tail[5] ? tail[6] : tail[4];
-                if (tail[7]) isERR = true;
-                conditions = {
-                  name,
-                  type,
-                  value,
-                };
-              };
-            };
-          } else if (tail[3]) {
-            name = null;
-          };
-        };
-      };
-    };
-  } else {
-    name = value;
-  };
-  name = evalXObjEName(name);
-  if (name === null) isERR = true;
-  result = {
-    name,
-    conditions,
-    isERR,
-  };
-  return result;
-};
-
-/**
- *
+ * A `Node`-element
  * @since 0.3.2
  * @typedef {Object<string, any>} INode
  */
@@ -260,7 +38,7 @@ function genXObjENameDescr(value) {
  */
 module.exports.INode = {};
 /**
- * A list of a `INode`-elements
+ * A list of a `Node`-elements
  * @since 0.3.2
  * @typedef {INode[]} INodeList
  */
@@ -268,7 +46,7 @@ module.exports.INode = {};
 /**
  * Extracts an element from a given object by its key.
  * @function getXObjElement
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} name - some child element
  * @returns {?any}
  * @throws {TypeError} if `obj` param is not an object
@@ -291,15 +69,6 @@ function getXObjElement(obj, name) {
 };
 module.exports.getXObjElement = getXObjElement;
 
-/**
- * A result of an xObj modification ops
- * @typedef {Object} RVAL_emodif
- * @property {boolean} isSucceed - flag that indicates whether an ops is succeed or not
- * @property {?(object|object[])} item - some element as a result
- * @deprecated
- * @todo \[from v0.3.2] make obsolete. Use `INodeModifResult` instead.
- */
-
 /**
  * A result of an xObj modification ops if failed
  * @since 0.3.2
@@ -307,33 +76,18 @@ module.exports.getXObjElement = getXObjElement;
  * @property {false} isSucceed - flag that indicates whether an ops is succeed or not
  * @property {null} item - some element as a result
  */
-
-/**
- * A result of an xObj modification ops if succeed
- * @since 0.3.2
- * @typedef {Object} INodeModifResultOnSuccess
- * @property {true} isSucceed - flag that indicates whether an ops is succeed or not
- * @property {object|object[]} item - some element as a result
- */
-
-/**
- * A result of an xObj modification ops
- * @since 0.3.2
- * @typedef {INodeModifResultOnFail|INodeModifResultOnSuccess} INodeModifResult
- */
-
 /**
  * A virtual constant meant for support jsdoc notation:
- * @type {INodeModifResult}
+ * @type {INodeModifResultOnFail}
  */
-module.exports.INodeModifResult = { isSucceed: false, item: null };
+module.exports.INodeModifResultOnFail = { isSucceed: false, item: null };
 
 /**
- *
+ * Function interface for adding some child element to `INode`
  * @callback addXObjElementFn
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} name - some child element
- * @returns {?object}
+ * @returns {?INode}
  * @see {@link addXObjElementEx} for param details
  */
 /**
@@ -360,13 +114,32 @@ function addXObjElement(...args) {
 };
 module.exports.addXObjElement = addXObjElement;
 
+/**
+ * A result of an xObj modification ops if succeed (when child element returned)
+ * @since 0.4.0
+ * @typedef {Object} INodeModifResultOnSuccess_S1
+ * @property {true} isSucceed - flag that indicates whether an ops is succeed or not
+ * @property {INode} item - some element as a result
+ */
+/**
+ * A virtual constant meant for support jsdoc notation:
+ * @type {INodeModifResultOnSuccess_S1}
+ */
+module.exports.INodeModifResultOnSuccess_S1 = { isSucceed: true, item: {} };
+
+/**
+ * A result of an xObj modification ops
+ * @since 0.4.0
+ * @typedef {INodeModifResultOnFail|INodeModifResultOnSuccess_S1} IAddNodeResult
+ */
+
 /**
  * Adds an element addressed by its key to a given object.
  * @since 0.3.0
  * @function addXObjElementEx
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} name - some child element
- * @returns {INodeModifResult}
+ * @returns {IAddNodeResult}
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
@@ -416,12 +189,12 @@ module.exports.addXObjElementEx = addXObjElementEx;
  */
 
 /**
- *
+ * Function interface for inserting some child element into `INode`
  * @callback insertXObjElementFn
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} name - some child element
  * @param {OPT_inselops_L} [opt] - options
- * @returns {?object}
+ * @returns {?INode|INode[]}
  * @see {@link insertXObjElementEx} for param details
  */
 /**
@@ -448,14 +221,33 @@ function insertXObjElement(...args) {
 };
 module.exports.insertXObjElement = insertXObjElement;
 
+/**
+ * A result of an xObj modification ops if succeed (when child element returned)
+ * @since 0.4.0
+ * @typedef {Object} INodeModifResultOnSuccess_S2
+ * @property {true} isSucceed - flag that indicates whether an ops is succeed or not
+ * @property {INode[]} item - some element as a result
+ */
+/**
+ * A virtual constant meant for support jsdoc notation:
+ * @type {INodeModifResultOnSuccess_S2}
+ */
+module.exports.INodeModifResultOnSuccess_S2 = { isSucceed: true, item: [] };
+
+/**
+ * A result of an xObj modification ops
+ * @since 0.4.0
+ * @typedef {INodeModifResultOnFail|INodeModifResultOnSuccess_S1|INodeModifResultOnSuccess_S2} IInsertNodeResult
+ */
+
 /**
  * Inserts an element addressed by its key into a given object.
  * @since 0.2.0
  * @function insertXObjElementEx
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} name - some child element
  * @param {OPT_inselops_L} [opt] - options
- * @returns {INodeModifResult}
+ * @returns {IInsertNodeResult}
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
@@ -504,9 +296,9 @@ function insertXObjElementEx(obj, name, opt) {
 module.exports.insertXObjElementEx = insertXObjElementEx;
 
 /**
- *
+ * Function interface for deleting some child element from `INode`
  * @callback deleteXObjElementFn
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} name - some child element
  * @returns {boolean}
  * @see {@link deleteXObjElementEx} for param details
@@ -535,12 +327,31 @@ function deleteXObjElement(...args) {
 };
 module.exports.deleteXObjElement = deleteXObjElement;
 
+/**
+ * A result of an xObj modification ops if succeed (when child element not returned)
+ * @since 0.4.0
+ * @typedef {Object} INodeModifResultOnSuccess_S0
+ * @property {true} isSucceed - flag that indicates whether an ops is succeed or not
+ * @property {null} item - some element as a result
+ */
+/**
+ * A virtual constant meant for support jsdoc notation:
+ * @type {INodeModifResultOnSuccess_S0}
+ */
+module.exports.INodeModifResultOnSuccess_S0 = { isSucceed: true, item: null };
+
+/**
+ * A result of an xObj modification ops
+ * @since 0.4.0
+ * @typedef {INodeModifResultOnFail|INodeModifResultOnSuccess_S0|INodeModifResultOnSuccess_S1|INodeModifResultOnSuccess_S2} IDeleteNodeResult
+ */
+
 /**
  * Deletes an element addressed by its key from a given object.
  * @function deleteXObjElementEx
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} name - some child element
- * @returns {INodeModifResult}
+ * @returns {IDeleteNodeResult}
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
@@ -557,9 +368,16 @@ function deleteXObjElementEx(obj, name) {
     let isSucceed = false;
     // // TODO: catch errors in strict mode
     isSucceed = delete obj[key];
-    return {
-      isSucceed,
-      item: isSucceed && isObject(prop) ? prop : null,
+    if (isSucceed) {
+      return {
+        isSucceed,
+        item: isObject(prop) ? prop : null,
+      };
+    } else {
+      return {
+        isSucceed,
+        item: null,
+      };
     };
   } else {
     const { code, msg } = key;
@@ -571,7 +389,7 @@ module.exports.deleteXObjElementEx = deleteXObjElementEx;
 /**
  * Renames an element addressed by its key.
  * @function renameXObjElement
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} name - some child element
  * @param {string} value - new element ID
  * @returns {boolean}
@@ -617,7 +435,7 @@ module.exports.renameXObjElement = renameXObjElement;
 /**
  * Inserts an elements into a given object.
  * @function insertXObjElements
- * @param {object} obj  - some object
+ * @param {INode} obj  - some object
  * @param {...string} name - some child element name
  * @param {OPT_inselops_L} [opt]
  * @returns {number}
@@ -652,15 +470,21 @@ function insertXObjElements(obj, ...args) {
  */
 
 /**
- * Inserts a list elements into a given object.
- * @function insertXObjEList
- * @param {object} obj - some object
+ *
+ * @callback insertXObjEListFn
+ * @param {INode} obj - some object
  * @param {string} name - some child element name
  * @param {OPT_inselops_S} [opt] - options
- * @returns {?(object|object[])}
+ * @returns {?INode[]}
+ * @see {@link insertXObjEListEx} for param details
+ */
+/**
+ * Inserts a list elements into a given object.
+ * @type {insertXObjEListFn}
  * @throws {TypeError} if `obj` param is not an object
  */
 function insertXObjEList(...args) {
+  /** @type {?INode[]} */
   let item = null;
   try {
     ({ item } = insertXObjEListEx(...args));
@@ -677,15 +501,16 @@ function insertXObjEList(...args) {
   };
   return item;
 };
+module.exports.insertXObjEList = insertXObjEList;
 
 /**
  * Inserts a list elements into a given object.
  * @since 0.2.0
  * @function insertXObjEListEx
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} name - some child element name
  * @param {OPT_inselops_S} [opt] - options
- * @returns {INodeModifResult}
+ * @returns {INodeModifResultOnFail|INodeModifResultOnSuccess_S2}
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
@@ -729,13 +554,14 @@ function insertXObjEListEx(obj, name, opt) {
     throw new EvalKeyNameError(msg, { code });
   };
 };
+module.exports.insertXObjEListEx = insertXObjEListEx;
 
 /**
  * Inserts a chain of an elements into a given object.
  * @function insertXObjEChain
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {...string} name - some child element name
- * @param {object} [opt] - options
+ * @param {OPT_inselops_L} [opt] - options
  * @returns {?any}
  * @throws {TypeError} if `obj` param is not an object
  * @experimental
@@ -760,18 +586,23 @@ function insertXObjEChain(obj, ...args) {
     let isSucceed = false;
     for (let key of args) {
       child = insertXObjElement(parent, key, opt);
-      isSucceed = isPlainObject(child);
-      if (!isSucceed) break;
-      parent = child;
+      if (isPlainObject(child)) {
+        parent = child;
+        isSucceed = true;
+      } else {
+        isSucceed = false;
+        break;
+      };
     };
     result = isSucceed ? parent : null;
   };
   return result;
 };
+module.exports.insertXObjEChain = insertXObjEChain;
 
 /**
  * Clears a given node
- * @param {object|object[]} node - some node
+ * @param {INode|INode[]} node - some node
  * @returns {boolean}
  * @throws {TypeError} if `node`-param is not an object or array
  */
@@ -798,11 +629,5 @@ module.exports.clearXObjNode = clearXObjNode;
 
 // === module exports block ===
 
-module.exports.evalXObjEName = evalXObjEName;
-module.exports.insertXObjEList = insertXObjEList;
-module.exports.insertXObjEListEx = insertXObjEListEx;
-
 // * experimental *
-module.exports.genXObjENameDescr = genXObjENameDescr;
 module.exports.insertXObjElements = insertXObjElements;
-module.exports.insertXObjEChain = insertXObjEChain;

package/lib/xObj-names.d.ts

@@ -0,0 +1,102 @@
+/**
+ * A result of `evalKeyName` function
+ */
+export type IEvalKeyNameResult = IEvalKeyNameResultOnSuccess | IEvalKeyNameResultOnFail;
+export const IEvalKeyNameResult: IEvalKeyNameResult;
+/**
+ * Some conditions applied to an element as a result of an element name pattern
+ * evaluation ops.
+ */
+export type IXObjENameDescrConditions = {
+    /**
+     * - element name
+     */
+    name: any;
+    /**
+     * - element type
+     */
+    type: any;
+    /**
+     * - some value
+     */
+    value?: any;
+};
+/**
+ * A result of an element name pattern evaluation ops.
+ */
+export type IXObjENameDescr = {
+    /**
+     * - ops flag
+     */
+    isERR: boolean;
+    /**
+     * - element name
+     */
+    name: null | number | string;
+    /**
+     * - some conditions applied to an element
+     */
+    conditions: IXObjENameDescrConditions | null;
+};
+/**
+ * An error description of a value check ops on fail.
+ */
+export type IEvalKeyNameReasonOnFail = {
+    /**
+     * - message ID
+     */
+    code: string;
+    /**
+     * - message text
+     */
+    msg: string;
+};
+/**
+ * An options setting for `evalKeyName` function
+ */
+export type IEvalKeyNameOptions = {
+    /**
+     * - a flag to accept only a non-empty string values
+     */
+    onlyNES?: boolean;
+};
+/**
+ * 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
+ */
+export type IEvalKeyNameResultOnFail = {
+    /**
+     * - ops flag
+     */
+    isSucceed: false;
+    /**
+     * - reason of fail
+     */
+    value: IEvalKeyNameReasonOnFail;
+};
+
+/**
+ * Tries to convert a value into an ID.
+ * @inner
+ */
+export function evalKeyName(value: any, opt?: boolean | IEvalKeyNameOptions): IEvalKeyNameResult;
+/**
+ * Tries to convert a value into an ID.
+ */
+export function evalXObjEName(value: any): null | number | string;
+/**
+ * Tries to convert a value into an element name description.
+ */
+export function genXObjENameDescr(value: any): IXObjENameDescr;