@ygracs/xobj-lib-js 0.3.1 → 0.3.3

package/lib/xObj-attr.js

@@ -0,0 +1,614 @@
+// [v0.3.140-20260607]
+
+// === module init block ===
+
+const {
+  valueToIndex,
+  readAsString, readAsBoolEx, readAsNumberEx,
+  isArray, isObject, isPlainObject,
+  // * import types definitions *
+  IValueToStringTransformOptions,
+} = require('@ygracs/bsfoc-lib-js');
+
+const {
+  EvalKeyNameError,
+  XOBJ_ECODE_TABLE,
+} = require('./xObj-errors');
+
+const {
+  XOBJ_DEF_TNAMES,
+} = require('./xObj-defs');
+
+const {
+  evalKeyName,
+  getXObjElement, insertXObjElement,
+  // * import types definitions *
+  INode,
+} = require('./xObj-lib');
+
+// === module inner block ===
+
+const {
+  XOBJ_TE_NSTR_ECODE,
+  XOBJ_TE_NPOBJ_EMSG,
+  XOBJ_TE_NPOBJ_ECODE,
+  XOBJ_TE_KNES_ECODE,
+} = XOBJ_ECODE_TABLE;
+
+const {
+  XOBJ_DEF_ATTR_TNAME,
+} = XOBJ_DEF_TNAMES;
+
+// === module main block ===
+
+/**
+ * Extracts an attributes from a given object by its key.
+ * @function getXObjAttributes
+ * @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
+ */
+function getXObjAttributes(obj, key = XOBJ_DEF_ATTR_TNAME) {
+  let result = null;
+  try {
+    result = getXObjElement(obj, key);
+  } catch (err) {
+    switch (err.code) {
+      case XOBJ_TE_NSTR_ECODE :
+      case XOBJ_TE_KNES_ECODE : {
+        break;
+      }
+      default: {
+        throw err;
+      }
+    };
+  };
+  return isPlainObject(result) ? result : null;
+};
+module.exports.getXObjAttributes = getXObjAttributes;
+
+/**
+ * Checks whether an attribute is exists.
+ * @function checkXObjAttribute
+ * @param {INode} obj - some object
+ * @param {string} attr - some attribute ID
+ * @param {string} [key] - some key
+ * @returns {boolean}
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `attr` param is not valid identifier
+ */
+function checkXObjAttribute(obj, attr = '', key) {
+  /** @type {?INode} */
+  let node = null;
+  try {
+    node = getXObjAttributes(obj, key);
+  } catch (err) {
+    throw err;
+  };
+  if (node === null) return false;
+  const { isSucceed, value: name } = evalKeyName(attr, false);
+  if (isSucceed) {
+    if (name === '') return false;
+    return node[name] !== undefined;
+  } else {
+    const { code, msg } = name;
+    throw new EvalKeyNameError(msg, { code });
+  };
+};
+module.exports.checkXObjAttribute = checkXObjAttribute;
+
+/**
+ * Deletes an attribute addressed by a given name.
+ * @function deleteXObjAttribute
+ * @param {INode} obj - some object
+ * @param {string} attr - some attribute ID
+ * @param {string} [key] - some key
+ * @returns {boolean}
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `attr` param is not valid identifier
+ */
+function deleteXObjAttribute(obj, attr = '', key) {
+  /** @type {?INode} */
+  let node = null;
+  try {
+    node = getXObjAttributes(obj, key);
+  } catch (err) {
+    throw err;
+  };
+  if (node === null) return false;
+  const { isSucceed, value: name } = evalKeyName(attr, false);
+  if (isSucceed) {
+    let isSucceed = false;
+    if (name !== '') {
+      // // TODO: catch errors in strict mode
+      isSucceed = delete node[name];
+    };
+    return isSucceed;
+  } else {
+    const { code, msg } = name;
+    throw new EvalKeyNameError(msg, { code });
+  };
+};
+module.exports.deleteXObjAttribute = deleteXObjAttribute;
+
+/**
+ * Renames an attribute addressed by a given name.
+ * @since 0.2.0
+ * @function renameXObjAttribute
+ * @param {INode} obj - some object
+ * @param {string} attr - some attribute ID
+ * @param {string} value - new attribute ID
+ * @param {string} [key] - some key
+ * @returns {boolean}
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `attr` param is not valid identifier
+ * @throws {EvalKeyNameError} if `value` param is not valid identifier
+ * @throws {EvalKeyNameError} if `key` param is not valid identifier
+ */
+function renameXObjAttribute(obj, attr = '', value = '', key = XOBJ_DEF_ATTR_TNAME) {
+  if (!isPlainObject(obj)) {
+    throw new EvalKeyNameError(
+      XOBJ_TE_NPOBJ_EMSG,
+      { code: XOBJ_TE_NPOBJ_ECODE },
+    );
+  };
+  const opt = false;
+  const { isSucceed, value: _key } = evalKeyName(key, opt);
+  if (isSucceed) {
+    let isSucceed = false;
+    if (_key !== '') {
+      let _obj = obj[_key];
+      if (isPlainObject(_obj)) {
+        const { isSucceed: isAcceptON, value: oname } = evalKeyName(attr, opt);
+        if (!isAcceptON) {
+          const { code, msg } = oname;
+          throw new EvalKeyNameError(msg, { code });
+        };
+        const { isSucceed: isAcceptNN, value: nname } = evalKeyName(value, opt);
+        if (!isAcceptNN) {
+          const { code, msg } = nname;
+          throw new EvalKeyNameError(msg, { code });
+        };
+        if (oname !== '' && oname in _obj && nname !== '') {
+          if (oname !== nname) {
+            _obj = Object.entries(_obj);
+            const index = _obj.findIndex((item) => item[0] === oname);
+            _obj[index][0] = nname;
+            obj[_key] = Object.fromEntries(_obj);
+          };
+          isSucceed = true;
+        };
+      };
+    };
+    return isSucceed;
+  } else {
+    const { code, msg } = _key;
+    throw new EvalKeyNameError(msg, { code });
+  };
+};
+module.exports.renameXObjAttribute = renameXObjAttribute;
+
+/**
+ * Extracts an attribute 'AS IS' from a given object.
+ * @function readXObjAttrRaw
+ * @param {INode} obj - some object
+ * @param {string} attr - some attribute
+ * @param {string} [key] - some key
+ * @returns {any}
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `attr` param is not valid identifier
+ */
+function readXObjAttrRaw(obj, attr = '', key) {
+  /** @type {?INode} */
+  let node = null;
+  try {
+    node = getXObjAttributes(obj, key);
+  } catch (err) {
+    throw err;
+  };
+  if (node !== null) {
+    const { isSucceed, value: name } = evalKeyName(attr, false);
+    if (isSucceed) {
+      if (name !== '') return node[name];
+    } else {
+      const { code, msg } = name;
+      throw new EvalKeyNameError(msg, { code });
+    };
+  };
+};
+module.exports.readXObjAttrRaw = readXObjAttrRaw;
+
+/**
+ * Writes a parameter into a given object.
+ * @function writeXObjAttrRaw
+ * @param {INode} obj - some object
+ * @param {string} attr - some attribute
+ * @param {any} value - some value
+ * @param {string} [key=XOBJ_DEF_ATTR_TNAME] - some key
+ * @returns {boolean}
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `attr` param is not valid identifier
+ */
+function writeXObjAttrRaw(obj, attr = '', value, key = XOBJ_DEF_ATTR_TNAME) {
+  const { isSucceed, value: name } = evalKeyName(attr, false);
+  if (isSucceed) {
+    let isSucceed = false;
+    if (
+      name !== ''
+      && value !== undefined
+      && !isObject(value)
+      && typeof value !== 'function'
+    ) {
+      let _obj = null;
+      try {
+        const opt = { force: true, acceptIfList: true };
+        _obj = insertXObjElement(obj, key, opt);
+      } catch (err) {
+        throw err;
+      };
+      if (isArray(_obj)) {
+        // force a replacement of the old element if it's array
+        try {
+          const opt = { force: true, ripOldies: true };
+          _obj = insertXObjElement(obj, key, opt);
+        } catch (err) {
+          throw err;
+        };
+      };
+      if (_obj !== null) {
+        _obj[name] = value;
+        isSucceed = true;
+      };
+    };
+    return isSucceed;
+  } else {
+    const { code, msg } = name;
+    throw new EvalKeyNameError(msg, { code });
+  };
+};
+module.exports.writeXObjAttrRaw = writeXObjAttrRaw;
+
+/**
+ * Extracts an attribute from a given object and returns it as a string.
+ * @function readXObjAttr
+ * @param {INode} obj - some object
+ * @param {string} attr - some attribute
+ * @param {string} [key] - some key
+ * @returns {string}
+ * @throws {TypeError} if `obj` param is not an object
+ */
+function readXObjAttr(obj, attr, key) {
+  const opt = {
+    useTrim: true,
+    numberToString: true,
+    boolToString: true,
+    defValue: '',
+  };
+  let result = undefined;
+  try {
+    result = readXObjAttrEx(obj, attr, opt, key);
+  } catch (err) {
+    throw err;
+  };
+  return result;
+};
+module.exports.readXObjAttr = readXObjAttr;
+
+/**
+ * Extracts an attribute from a given object and returns it as a boolean.
+ * @function readXObjAttrAsBool
+ * @param {INode} obj - some object
+ * @param {string} attr - some attribute
+ * @param {boolean} [defValue] - default value
+ * @param {string} [key] - some key
+ * @returns {boolean}
+ * @throws {TypeError} if `obj` param is not an object
+ * @see readAsBoolEx from `@ygracs/bsfoc-lib-js` on details for result
+ */
+function readXObjAttrAsBool(obj, attr, defValue, key) {
+  let result = undefined;
+  try {
+    result = readXObjAttrRaw(obj, attr, key);
+  } catch (err) {
+    switch (err.code) {
+      case XOBJ_TE_NSTR_ECODE : {
+        break;
+      }
+      default: {
+        throw err;
+      }
+    };
+  };
+  return readAsBoolEx(result, defValue);
+};
+module.exports.readXObjAttrAsBool = readXObjAttrAsBool;
+
+/**
+ * Extracts an attribute from a given object and returns it as a number.
+ * @function readXObjAttrAsNum
+ * @param {INode} obj - some object
+ * @param {string} attr - some attribute
+ * @param {number} [defValue] - default value
+ * @param {string} [key] - some key
+ * @returns {number}
+ * @throws {TypeError} if `obj` param is not an object
+ * @see readAsNumberEx from `@ygracs/bsfoc-lib-js` on details for result
+ */
+function readXObjAttrAsNum(obj, attr, defValue, key) {
+  let result = undefined;
+  try {
+    result = readXObjAttrRaw(obj, attr, key);
+  } catch (err) {
+    switch (err.code) {
+      case XOBJ_TE_NSTR_ECODE : {
+        break;
+      }
+      default: {
+        throw err;
+      }
+    };
+  };
+  return readAsNumberEx(result, defValue);
+};
+module.exports.readXObjAttrAsNum = readXObjAttrAsNum;
+
+/**
+ * Extracts an attribute from a given object and returns it as 'index' value.
+ * @function readXObjAttrAsIndex
+ * @param {INode} obj - some object
+ * @param {string} attr - some attribute
+ * @param {string} [key] - some key
+ * @returns {number}
+ * @throws {TypeError} if `obj` param is not an object
+ */
+function readXObjAttrAsIndex(obj, attr, key) {
+  let result = undefined;
+  try {
+    result = readXObjAttrRaw(obj, attr, key);
+  } catch (err) {
+    switch (err.code) {
+      case XOBJ_TE_NSTR_ECODE : {
+        break;
+      }
+      default: {
+        throw err;
+      }
+    };
+  };
+  return valueToIndex(result);
+};
+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 {INode} obj - some object
+ * @param {string} attr - some attribute
+ * @param {readXObjAttrOptionAsStr|IValueToStringTransformOptions} [opt] - options
+ * @param {string} [key] - some key
+ * @returns {string}
+ * @throws {TypeError} if `obj` param is not an object
+ * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
+ */
+function readXObjAttrEx(obj, attr, opt, key) {
+  let result = undefined;
+  try {
+    result = readXObjAttrRaw(obj, attr, key);
+  } catch (err) {
+    switch (err.code) {
+      case XOBJ_TE_NSTR_ECODE : {
+        break;
+      }
+      default: {
+        throw err;
+      }
+    };
+  };
+  const _opt = isPlainObject(opt) ? opt : {
+    useTrim: true,
+    numberToString: true,
+    boolToString: true,
+    defValue: opt,
+  };
+  return readAsString(result, _opt);
+};
+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 {INode} obj - some object
+ * @param {string} attr - some attribute
+ * @param {any} value - some value
+ * @param {string} [key] - some key
+ * @returns {boolean}
+ * @throws {TypeError} if `obj` param is not an object
+ */
+function writeXObjAttr(obj, attr, value, key) {
+  let isSucceed = false;
+  try {
+    const opt = {
+      useTrim: true,
+      numberToString: true,
+      boolToString: true,
+      defValue: '',
+    };
+    isSucceed = writeXObjAttrEx(obj, attr, value, opt, key);
+  } catch (err) {
+    throw err;
+  };
+  return isSucceed;
+};
+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 {INode} obj - some object
+ * @param {string} attr - some attribute
+ * @param {any} value - some value
+ * @param {boolean} [defValue] - default value
+ * @param {string} [key] - some key
+ * @returns {boolean}
+ * @throws {TypeError} if `obj` param is not an object
+ */
+function writeXObjAttrAsBool(obj, attr, value, defValue, key) {
+  let isSucceed = false;
+  if (value !== undefined || typeof defValue === 'boolean') {
+    const _value = readAsBoolEx(value, defValue).toString();
+    try {
+      isSucceed = writeXObjAttrRaw(obj, attr, _value, key);
+    } catch (err) {
+      switch (err.code) {
+        case XOBJ_TE_NSTR_ECODE : {
+          break;
+        }
+        default: {
+          throw err;
+        }
+      };
+    };
+  };
+  return isSucceed;
+};
+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 {INode} obj - some object
+ * @param {string} attr - some attribute
+ * @param {any} value - some value
+ * @param {number} [defValue] - default value
+ * @param {string} [key] - some key
+ * @returns {boolean}
+ * @throws {TypeError} if `obj` param is not an object
+ */
+function writeXObjAttrAsNum(obj, attr, value, defValue, key) {
+  let isSucceed = false;
+  if (value !== undefined || typeof defValue === 'number') {
+    const _value = readAsNumberEx(value, defValue).toString();
+    try {
+      isSucceed = writeXObjAttrRaw(obj, attr, _value, key);
+    } catch (err) {
+      switch (err.code) {
+        case XOBJ_TE_NSTR_ECODE : {
+          break;
+        }
+        default: {
+          throw err;
+        }
+      };
+    };
+  };
+  return isSucceed;
+};
+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 {INode} obj - some object
+ * @param {string} attr - some attribute
+ * @param {any} value - some value
+ * @param {string} [key] - some key
+ * @returns {boolean}
+ * @throws {TypeError} if `obj` param is not an object
+ */
+function writeXObjAttrAsIndex(obj, attr, value, key) {
+  let isSucceed = false;
+  if (value !== undefined) {
+    const _value = valueToIndex(value).toString();
+    try {
+      isSucceed = writeXObjAttrRaw(obj, attr, _value, key);
+    } catch (err) {
+      switch (err.code) {
+        case XOBJ_TE_NSTR_ECODE : {
+          break;
+        }
+        default: {
+          throw err;
+        }
+      };
+    };
+  };
+  return isSucceed;
+};
+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 {INode} obj - some object
+ * @param {string} attr - some attribute
+ * @param {any} value - some value
+ * @param {writeXObjAttrOptionAsStr|IValueToStringTransformOptions} [opt] - options
+ * @param {string} [key] - some key
+ * @returns {boolean}
+ * @throws {TypeError} if `obj` param is not an object
+ * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
+ */
+function writeXObjAttrEx(obj, attr, value, opt, key) {
+  let isSucceed = false;
+  if (value !== undefined && typeof value !== 'function') {
+    let _opt = opt;
+    if (!isPlainObject(_opt)) {
+      const defValue = readAsString(_opt, {
+        useTrim: true,
+        numberToString: true,
+        boolToString: true,
+      });
+      _opt = {
+        useTrim: true,
+        numberToString: true,
+        boolToString: true,
+        defValue,
+      };
+    };
+    const _value = readAsString(value, _opt);
+    try {
+      isSucceed = writeXObjAttrRaw(obj, attr, _value, key);
+    } catch (err) {
+      switch (err.code) {
+        case XOBJ_TE_NSTR_ECODE : {
+          break;
+        }
+        default: {
+          throw err;
+        }
+      };
+    };
+  };
+  return isSucceed;
+};
+module.exports.writeXObjAttrEx = writeXObjAttrEx;