@ygracs/xobj-lib-js 0.3.2 → 0.4.0

package/lib/xObj-names.js

@@ -0,0 +1,219 @@
+// [v0.3.141-20260629]
+
+// === module init block ===
+
+const {
+  valueToIndex,
+  isInteger,
+  isPlainObject,
+} = require('@ygracs/bsfoc-lib-js');
+
+const {
+  XOBJ_ECODE_TABLE,
+} = require('./xObj-errors');
+
+// === module inner block ===
+
+const {
+  XOBJ_TE_NSTR_EMSG,
+  XOBJ_TE_NSTR_ECODE,
+  XOBJ_TE_KNES_EMSG,
+  XOBJ_TE_KNES_ECODE,
+} = XOBJ_ECODE_TABLE;
+
+// === module main block ===
+
+/**
+ * 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
+ */
+
+/**
+ * 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;
+
+/**
+ * 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;
+};
+module.exports.evalXObjEName = evalXObjEName;
+
+/**
+ * Some conditions applied to an element as a result of an element name pattern
+ * evaluation ops.
+ * @since 0.3.0
+ * @typedef {Object} IXObjENameDescrConditions
+ * @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} IXObjENameDescr
+ * @property {boolean} isERR - ops flag
+ * @property {null|number|string} name - element name
+ * @property {?IXObjENameDescrConditions} 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 {IXObjENameDescr}
+ * @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;
+};
+module.exports.genXObjENameDescr = genXObjENameDescr;

package/lib/xObj-param.d.ts

@@ -1,69 +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: object, key?: string): any;
+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: object, value: any, key?: string): boolean;
+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: object, defValue?: boolean, key?: string): boolean;
+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: object, defValue?: number, key?: string): number;
+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: object, key?: string): number;
+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: object, opt?: object, key?: string): 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: object, value: any, defValue?: boolean, key?: string): boolean;
+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: object, value: any, defValue?: number, key?: string): boolean;
+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: object, value: any, key?: string): boolean;
+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: object, value: any, opt?: object, 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: object, 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: object, value: any, key?: string): boolean;
+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

@@ -1,4 +1,4 @@
-// [v0.3.138-20260530]
+// [v0.3.141-20260629]
 
 // === module init block ===
 
@@ -21,6 +21,11 @@ const {
 
 const {
   evalKeyName,
+} = require('./xObj-names');
+
+const {
+  // * import types definitions *
+  INode,
 } = require('./xObj-lib');
 
 // === module inner block ===
@@ -40,7 +45,7 @@ const {
 /**
  * Extracts a parameter 'AS IS' from a given object.
  * @function readXObjParamRaw
- * @param {object} obj - some object
+ * @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
@@ -65,7 +70,7 @@ module.exports.readXObjParamRaw = readXObjParamRaw;
 /**
  * Writes a parameter 'AS IS' into a given object.
  * @function writeXObjParamRaw
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {any} value - some value
  * @param {string} [key=XOBJ_DEF_PARAM_TNAME] - some key
  * @returns {boolean}
@@ -101,7 +106,7 @@ module.exports.writeXObjParamRaw = writeXObjParamRaw;
 /**
  * Extracts a parameter from a given object and returns it as a string.
  * @function readXObjParam
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} [key] - some key
  * @returns {string}
  * @throws {TypeError} if `obj` param is not an object
@@ -126,7 +131,7 @@ module.exports.readXObjParam = readXObjParam;
 /**
  * Extracts a parameter from a given object and returns it as a boolean.
  * @function readXObjParamAsBool
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {boolean} [defValue] - default value
  * @param {string} [key] - some key
  * @returns {boolean}
@@ -154,7 +159,7 @@ module.exports.readXObjParamAsBool = readXObjParamAsBool;
 /**
  * Extracts a parameter from a given object and returns it as a number.
  * @function readXObjParamAsNum
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {number} [defValue] - default value
  * @param {string} [key] - some key
  * @returns {number}
@@ -182,7 +187,7 @@ module.exports.readXObjParamAsNum = readXObjParamAsNum;
 /**
  * Extracts a parameter from a given object and returns it as 'index' value.
  * @function readXObjParamAsIndex
- * @param {object} obj - some object
+ * @param {INode} obj - some object
  * @param {string} [key] - some key
  * @returns {number}
  * @throws {TypeError} if `obj` param is not an object
@@ -205,11 +210,23 @@ function readXObjParamAsIndex(obj, key) {
 };
 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 {object} obj - some object
- * @param {object} [opt] - options
+ * @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
@@ -229,7 +246,6 @@ function readXObjParamEx(obj, opt, key) {
       }
     };
   };
-  /** @type {IValueToStringTransformOptions} */
   const _opt = isPlainObject(opt) ? opt : {
     useTrim: false,
     numberToString: true,
@@ -244,7 +260,7 @@ 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 {object} obj - some object
+ * @param {INode} obj - some object
  * @param {any} value - some value
  * @param {string} [key] - some key
  * @returns {boolean}
@@ -271,7 +287,7 @@ 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 {object} obj - some object
+ * @param {INode} obj - some object
  * @param {any} value - some value
  * @param {boolean} [defValue] - default value
  * @param {string} [key] - some key
@@ -303,7 +319,7 @@ 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 {object} obj - some object
+ * @param {INode} obj - some object
  * @param {any} value - some value
  * @param {number} [defValue] - default value
  * @param {string} [key] - some key
@@ -335,7 +351,7 @@ 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 {object} obj - some object
+ * @param {INode} obj - some object
  * @param {any} value - some value
  * @param {string} [key] - some key
  * @returns {boolean}
@@ -362,13 +378,25 @@ function writeXObjParamAsIndex(obj, value, key) {
 };
 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 {object} obj - some object
+ * @param {INode} obj - some object
  * @param {any} value - some value
- * @param {object} [opt] - options
+ * @param {writeXObjParamOptionAsStr|IValueToStringTransformOptions} [opt] - options
  * @param {string} [key] - some key
  * @returns {boolean}
  * @throws {TypeError} if `obj` param is not an object

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ygracs/xobj-lib-js",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "A helper library to work with xml-js module",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -14,6 +14,7 @@
     "doc/*.md",
     "lib/xObj-lib.js",
     "lib/xObj-defs.js",
+    "lib/xObj-names.js",
     "lib/xObj-errors.js",
     "lib/xObj-attr.js",
     "lib/xObj-param.js",
@@ -33,7 +34,7 @@
     "#test-dir/*": "./__test__/*"
   },
   "dependencies": {
-    "@ygracs/bsfoc-lib-js": "~0.3.4"
+    "@ygracs/bsfoc-lib-js": "~0.4.0"
   },
   "devDependencies": {
     "@ygracs/test-helper": "~0.0.2-b",