@ygracs/xobj-lib-js 0.3.1 → 0.3.3

package/lib/xObj-param.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @deprecated
+ * @todo \[since `v0.2.1`] deprecated and will be removed
+ */
+export type readXObjParamOptionAsStr = string;
+export const readXObjParamOptionAsStr: readXObjParamOptionAsStr;
+/**
+ * @deprecated
+ * @todo \[since `v0.2.1`] deprecated and will be removed
+ */
+export type writeXObjParamOptionAsStr = string;
+export const writeXObjParamOptionAsStr: writeXObjParamOptionAsStr;
+/**
+ * Extracts a parameter 'AS IS' from a given object.
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `key` param is not valid identifier
+ */
+export function readXObjParamRaw(obj: INode, key?: string): any;
+/**
+ * Writes a parameter 'AS IS' into a given object.
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `key` param is not valid identifier
+ */
+export function writeXObjParamRaw(obj: INode, value: any, key?: string): boolean;
+/**
+ * Extracts a parameter from a given object and returns it as a string.
+ * @throws {TypeError} if `obj` param is not an object
+ */
+export function readXObjParam(obj: INode, key?: string): string;
+/**
+ * Extracts a parameter from a given object and returns it as a boolean.
+ * @throws {TypeError} if `obj` param is not an object
+ */
+export function readXObjParamAsBool(obj: INode, defValue?: boolean, key?: string): boolean;
+/**
+ * Extracts a parameter from a given object and returns it as a number.
+ * @throws {TypeError} if `obj` param is not an object
+ */
+export function readXObjParamAsNum(obj: INode, defValue?: number, key?: string): number;
+/**
+ * Extracts a parameter from a given object and returns it as 'index' value.
+ * @throws {TypeError} if `obj` param is not an object
+ */
+export function readXObjParamAsIndex(obj: INode, key?: string): number;
+/**
+ * Extracts a parameter from a given object and returns it as a string.
+ * @throws {TypeError} if `obj` param is not an object
+ * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
+ */
+export function readXObjParamEx(obj: INode, opt?: readXObjParamOptionAsStr | IValueToStringTransformOptions, key?: string): string;
+/**
+ * Tries to convert a given value to a string and writes it as a parameter
+ * into a given object.
+ * @throws {TypeError} if `obj` param is not an object
+ */
+export function writeXObjParam(obj: INode, 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 `obj` param is not an object
+ */
+export function writeXObjParamAsBool(obj: INode, 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 `obj` param is not an object
+ */
+export function writeXObjParamAsNum(obj: INode, 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 `obj` param is not an object
+ */
+export function writeXObjParamAsIndex(obj: INode, 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 `obj` param is not an object
+ * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
+ */
+export function writeXObjParamEx(obj: INode, value: any, opt?: writeXObjParamOptionAsStr | IValueToStringTransformOptions, key?: string): boolean;
+import type { INode } from "./xObj-lib";
+import type { IValueToStringTransformOptions } from "@ygracs/bsfoc-lib-js";

package/lib/xObj-param.js

@@ -0,0 +1,435 @@
+// [v0.3.140-20260607]
+
+// === module init block ===
+
+const {
+  valueToIndex,
+  readAsString, readAsBoolEx, readAsNumberEx,
+  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,
+  // * import types definitions *
+  INode,
+} = require('./xObj-lib');
+
+// === module inner block ===
+
+const {
+  XOBJ_TE_NSTR_ECODE,
+  XOBJ_TE_NPOBJ_EMSG,
+  XOBJ_TE_NPOBJ_ECODE,
+} = XOBJ_ECODE_TABLE;
+
+const {
+  XOBJ_DEF_PARAM_TNAME,
+} = XOBJ_DEF_TNAMES;
+
+// === module main block ===
+
+/**
+ * Extracts a parameter 'AS IS' from a given object.
+ * @function readXObjParamRaw
+ * @param {INode} obj - some object
+ * @param {string} [key=XOBJ_DEF_PARAM_TNAME] - some key
+ * @returns {any}
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `key` param is not valid identifier
+ */
+function readXObjParamRaw(obj, key = XOBJ_DEF_PARAM_TNAME) {
+  if (!isPlainObject(obj)) {
+    throw new EvalKeyNameError(
+      XOBJ_TE_NPOBJ_EMSG,
+      { code: XOBJ_TE_NPOBJ_ECODE },
+    );
+  };
+  const { isSucceed, value: _key } = evalKeyName(key, false);
+  if (!isSucceed) {
+    const { code, msg } = _key;
+    throw new EvalKeyNameError(msg, { code });
+  };
+  return _key !== '' ? obj[_key] : undefined;
+};
+module.exports.readXObjParamRaw = readXObjParamRaw;
+
+/**
+ * Writes a parameter 'AS IS' into a given object.
+ * @function writeXObjParamRaw
+ * @param {INode} obj - some object
+ * @param {any} value - some value
+ * @param {string} [key=XOBJ_DEF_PARAM_TNAME] - some key
+ * @returns {boolean}
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `key` param is not valid identifier
+ */
+function writeXObjParamRaw(obj, value, key = XOBJ_DEF_PARAM_TNAME) {
+  if (!isPlainObject(obj)) {
+    throw new EvalKeyNameError(
+      XOBJ_TE_NPOBJ_EMSG,
+      { code: XOBJ_TE_NPOBJ_ECODE },
+    );
+  };
+  const { isSucceed, value: _key } = evalKeyName(key, false);
+  if (isSucceed) {
+    if (
+      _key === ''
+      || value === undefined
+      || isObject(value)
+      || typeof value === 'function'
+    ) {
+      return false;
+    };
+    obj[_key] = value;
+    return true;
+  } else {
+    const { code, msg } = _key;
+    throw new EvalKeyNameError(msg, { code });
+  };
+};
+module.exports.writeXObjParamRaw = writeXObjParamRaw;
+
+/**
+ * Extracts a parameter from a given object and returns it as a string.
+ * @function readXObjParam
+ * @param {INode} obj - some object
+ * @param {string} [key] - some key
+ * @returns {string}
+ * @throws {TypeError} if `obj` param is not an object
+ */
+function readXObjParam(obj, key) {
+  const opt = {
+    useTrim: false,
+    numberToString: true,
+    boolToString: true,
+    defValue: '',
+  };
+  let result = undefined;
+  try {
+    result = readXObjParamEx(obj, opt, key);
+  } catch (err) {
+    throw err;
+  };
+  return result;
+};
+module.exports.readXObjParam = readXObjParam;
+
+/**
+ * Extracts a parameter from a given object and returns it as a boolean.
+ * @function readXObjParamAsBool
+ * @param {INode} obj - some object
+ * @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 readXObjParamAsBool(obj, defValue, key) {
+  let result = undefined;
+  try {
+    result = readXObjParamRaw(obj, key);
+  } catch (err) {
+    switch (err.code) {
+      case XOBJ_TE_NSTR_ECODE : {
+        break;
+      }
+      default: {
+        throw err;
+      }
+    };
+  };
+  return readAsBoolEx(result, defValue);
+};
+module.exports.readXObjParamAsBool = readXObjParamAsBool;
+
+/**
+ * Extracts a parameter from a given object and returns it as a number.
+ * @function readXObjParamAsNum
+ * @param {INode} obj - some object
+ * @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 readXObjParamAsNum(obj, defValue, key) {
+  let result = undefined;
+  try {
+    result = readXObjParamRaw(obj, key);
+  } catch (err) {
+    switch (err.code) {
+      case XOBJ_TE_NSTR_ECODE : {
+        break;
+      }
+      default: {
+        throw err;
+      }
+    };
+  };
+  return readAsNumberEx(result, defValue);
+};
+module.exports.readXObjParamAsNum = readXObjParamAsNum;
+
+/**
+ * Extracts a parameter from a given object and returns it as 'index' value.
+ * @function readXObjParamAsIndex
+ * @param {INode} obj - some object
+ * @param {string} [key] - some key
+ * @returns {number}
+ * @throws {TypeError} if `obj` param is not an object
+ */
+function readXObjParamAsIndex(obj, key) {
+  let result = undefined;
+  try {
+    result = readXObjParamRaw(obj, key);
+  } catch (err) {
+    switch (err.code) {
+      case XOBJ_TE_NSTR_ECODE : {
+        break;
+      }
+      default: {
+        throw err;
+      }
+    };
+  };
+  return valueToIndex(result);
+};
+module.exports.readXObjParamAsIndex = readXObjParamAsIndex;
+
+/**
+ *
+ * @typedef {string} readXObjParamOptionAsStr
+ * @deprecated
+ * @todo \[since `v0.2.1`] deprecated and will be removed
+ */
+/**
+ * A virtual constant meant for support jsdoc notation:
+ * @type {readXObjParamOptionAsStr}
+ */
+module.exports.readXObjParamOptionAsStr = '';
+
+/**
+ * Extracts a parameter from a given object and returns it as a string.
+ * @function readXObjParamEx
+ * @param {INode} obj - some object
+ * @param {readXObjParamOptionAsStr|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 readXObjParamEx(obj, opt, key) {
+  let result = undefined;
+  try {
+    result = readXObjParamRaw(obj, key);
+  } catch (err) {
+    switch (err.code) {
+      case XOBJ_TE_NSTR_ECODE : {
+        break;
+      }
+      default: {
+        throw err;
+      }
+    };
+  };
+  const _opt = isPlainObject(opt) ? opt : {
+    useTrim: false,
+    numberToString: true,
+    boolToString: true,
+    defValue: opt,
+  };
+  return readAsString(result, _opt);
+};
+module.exports.readXObjParamEx = readXObjParamEx;
+
+/**
+ * Tries to convert a given value to a string and writes it as a parameter
+ * into a given object.
+ * @function writeXObjParam
+ * @param {INode} obj - some object
+ * @param {any} value - some value
+ * @param {string} [key] - some key
+ * @returns {boolean}
+ * @throws {TypeError} if `obj` param is not an object
+ */
+function writeXObjParam(obj, value, key) {
+  let isSucceed = false;
+  try {
+    const opt = {
+      useTrim: false,
+      numberToString: true,
+      boolToString: true,
+      defValue: '',
+    };
+    isSucceed = writeXObjParamEx(obj, value, opt, key);
+  } catch (err) {
+    throw err;
+  };
+  return isSucceed;
+};
+module.exports.writeXObjParam = writeXObjParam;
+
+/**
+ * Tries to convert a given value to a boolean and writes it as a parameter
+ * into a given object.
+ * @function writeXObjParamAsBool
+ * @param {INode} obj - some object
+ * @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 writeXObjParamAsBool(obj, value, defValue, key) {
+  let isSucceed = false;
+  if (value !== undefined || typeof defValue === 'boolean') {
+    const _value = readAsBoolEx(value, defValue).toString();
+    try {
+      isSucceed = writeXObjParamRaw(obj, _value, key);
+    } catch (err) {
+      switch (err.code) {
+        case XOBJ_TE_NSTR_ECODE : {
+          break;
+        }
+        default: {
+          throw err;
+        }
+      };
+    };
+  };
+  return isSucceed;
+};
+module.exports.writeXObjParamAsBool = writeXObjParamAsBool;
+
+/**
+ * Tries to convert a given value to a number and writes it as a parameter
+ * into a given object.
+ * @function writeXObjParamAsNum
+ * @param {INode} obj - some object
+ * @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 writeXObjParamAsNum(obj, value, defValue, key) {
+  let isSucceed = false;
+  if (value !== undefined || typeof defValue === 'number') {
+    const _value = readAsNumberEx(value, defValue).toString();
+    try {
+      isSucceed = writeXObjParamRaw(obj, _value, key);
+    } catch (err) {
+      switch (err.code) {
+        case XOBJ_TE_NSTR_ECODE : {
+          break;
+        }
+        default: {
+          throw err;
+        }
+      };
+    };
+  };
+  return isSucceed;
+};
+module.exports.writeXObjParamAsNum = writeXObjParamAsNum;
+
+/**
+ * Tries to convert a given value into an 'index' value and writes it
+ * as a parameter into a given object.
+ * @function writeXObjParamAsIndex
+ * @param {INode} obj - some object
+ * @param {any} value - some value
+ * @param {string} [key] - some key
+ * @returns {boolean}
+ * @throws {TypeError} if `obj` param is not an object
+ */
+function writeXObjParamAsIndex(obj, value, key) {
+  let isSucceed = false;
+  if (value !== undefined) {
+    const _value = valueToIndex(value).toString();
+    try {
+      isSucceed = writeXObjParamRaw(obj, _value, key);
+    } catch (err) {
+      switch (err.code) {
+        case XOBJ_TE_NSTR_ECODE : {
+          break;
+        }
+        default: {
+          throw err;
+        }
+      };
+    };
+  };
+  return isSucceed;
+};
+module.exports.writeXObjParamAsIndex = writeXObjParamAsIndex;
+
+/**
+ *
+ * @typedef {string} writeXObjParamOptionAsStr
+ * @deprecated
+ * @todo \[since `v0.2.1`] deprecated and will be removed
+ */
+/**
+ * A virtual constant meant for support jsdoc notation:
+ * @type {writeXObjParamOptionAsStr}
+ */
+module.exports.writeXObjParamOptionAsStr = '';
+
+/**
+ * Tries to convert a given value to a string and writes it
+ * as a parameter into a given object.
+ * @function writeXObjParamEx
+ * @param {INode} obj - some object
+ * @param {any} value - some value
+ * @param {writeXObjParamOptionAsStr|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 writeXObjParamEx(obj, value, opt, key) {
+  let isSucceed = false;
+  if (value !== undefined && typeof value !== 'function') {
+    let _opt = opt;
+    if (!isPlainObject(_opt)) {
+      const defValue = readAsString(_opt, {
+        useTrim: false,
+        numberToString: true,
+        boolToString: true,
+      });
+      _opt = {
+        useTrim: false,
+        numberToString: true,
+        boolToString: true,
+        defValue,
+      };
+    };
+    const _value = readAsString(value, _opt);
+    try {
+      isSucceed = writeXObjParamRaw(obj, _value, key);
+    } catch (err) {
+      switch (err.code) {
+        case XOBJ_TE_NSTR_ECODE : {
+          break;
+        }
+        default: {
+          throw err;
+        }
+      };
+    };
+  };
+  return isSucceed;
+};
+module.exports.writeXObjParamEx = writeXObjParamEx;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ygracs/xobj-lib-js",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "A helper library to work with xml-js module",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -15,6 +15,8 @@
     "lib/xObj-lib.js",
     "lib/xObj-defs.js",
     "lib/xObj-errors.js",
+    "lib/xObj-attr.js",
+    "lib/xObj-param.js",
     "lib/*.d.ts",
     "index.js",
     "index.d.ts",
@@ -35,7 +37,7 @@
   },
   "devDependencies": {
     "@ygracs/test-helper": "~0.0.2-b",
-    "jest": "^30.2.0",
+    "jest": "^30.4.2",
     "jsdoc-to-markdown": "^9.1.3",
     "minimist": "^1.2.8",
     "typescript": "~5.9.3"