@ygracs/xobj-lib-js 0.3.3 → 0.4.1

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.js

@@ -1,4 +1,4 @@
-// [v0.3.140-20260607]
+// [v0.3.141-20260629]
 
 // === module init block ===
 
@@ -21,6 +21,9 @@ const {
 
 const {
   evalKeyName,
+} = require('./xObj-names');
+
+const {
   // * import types definitions *
   INode,
 } = require('./xObj-lib');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ygracs/xobj-lib-js",
-  "version": "0.3.3",
+  "version": "0.4.1",
   "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",