@ygracs/xobj-lib-js 0.3.3 → 0.4.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+#### *v0.4.0*
+
+Release version.
+
+> - update dependency on `@ygracs/bsfoc-lib-js` module to v0.4.0;
+> - some fixes.
+
 #### *v0.3.3*
 
 Release version.

package/index.d.ts

@@ -1,6 +1,9 @@
 import { TXmlContentParseOptions } from "./lib/xObj-defs";
 import { DEF_XML_PARSE_OPTIONS } from "./lib/xObj-defs";
 import { XOBJ_DEF_TNAMES } from "./lib/xObj-defs";
+import { EvalKeyNameError } from "./lib/xObj-errors";
+import { evalXObjEName } from "./lib/xObj-names";
+import { genXObjENameDescr } from "./lib/xObj-names";
 
 export {
     TXmlContentParseOptions,
@@ -8,6 +11,8 @@ export {
     XOBJ_DEF_TNAMES,
 };
 
+export { EvalKeyNameError };
+
 import type {
     xml2jsParseOptions, js2xmlParseOptions,
     OPT_parserOptions,
@@ -18,10 +23,6 @@ export type {
     OPT_parserOptions,
 };
 
-import { EvalKeyNameError } from "./lib/xObj-errors";
-
-export { EvalKeyNameError };
-
 import {
     readXObjAttrRaw,
     readXObjAttr,
@@ -55,9 +56,6 @@ import {
     deleteXObjElement, deleteXObjElementEx,
     renameXObjElement,
     insertXObjEList, insertXObjEListEx,
-    evalXObjEName,
-    evalKeyName,
-    genXObjENameDescr,
     insertXObjElements,
     insertXObjEChain,
     clearXObjNode,
@@ -91,7 +89,6 @@ export {
     renameXObjElement,
     insertXObjEList, insertXObjEListEx,
     evalXObjEName,
-    evalKeyName,
     genXObjENameDescr,
     insertXObjElements,
     insertXObjEChain,
@@ -99,19 +96,18 @@ export {
 };
 
 import type {
-    XObjENameDescr, XObjENameDescrConditions,
-    OPT_inselops_L, OPT_inselops_S,
-    RVAL_emodif,
-    VCOR_evalkname, RVAL_reason,
+    IXObjENameDescr, IXObjENameDescrConditions,
     IEvalKeyNameResult,
+} from "./lib/xObj-names";
+
+import type {
+    OPT_inselops_L, OPT_inselops_S,
     INode,
 } from "./lib/xObj-lib";
 
 export type {
-    XObjENameDescr, XObjENameDescrConditions,
+    IXObjENameDescr, IXObjENameDescrConditions,
     OPT_inselops_L, OPT_inselops_S,
-    RVAL_emodif,
-    VCOR_evalkname, RVAL_reason,
     IEvalKeyNameResult,
     INode,
 };

package/index.js

@@ -1,4 +1,4 @@
-// [v0.1.017-20260606]
+// [v0.1.019-20260630]
 
 // === module init block ===
 
@@ -12,6 +12,11 @@ const {
   EvalKeyNameError,
 } = require('./lib/xObj-errors');
 
+const {
+  evalXObjEName,
+  genXObjENameDescr,
+} = require('./lib/xObj-names');
+
 const xObjAttr = require('./lib/xObj-attr');
 
 const xObjParam = require('./lib/xObj-param');
@@ -30,6 +35,9 @@ module.exports.XOBJ_DEF_TNAMES = XOBJ_DEF_TNAMES;
 
 module.exports.EvalKeyNameError = EvalKeyNameError;
 
+module.exports.evalXObjEName = evalXObjEName;
+module.exports.genXObjENameDescr = genXObjENameDescr;
+
 module.exports.readXObjParamRaw = xObjParam.readXObjParamRaw;
 module.exports.readXObjParam = xObjParam.readXObjParam;
 module.exports.readXObjParamAsBool = xObjParam.readXObjParamAsBool;
@@ -70,11 +78,9 @@ module.exports.deleteXObjElement = xObj.deleteXObjElement;
 module.exports.deleteXObjElementEx = xObj.deleteXObjElementEx;
 module.exports.renameXObjElement = xObj.renameXObjElement;
 
-module.exports.evalXObjEName = xObj.evalXObjEName;
 module.exports.insertXObjEList = xObj.insertXObjEList;
 module.exports.insertXObjEListEx = xObj.insertXObjEListEx;
 
-module.exports.genXObjENameDescr = xObj.genXObjENameDescr;
 module.exports.insertXObjElements = xObj.insertXObjElements;
 module.exports.insertXObjEChain = xObj.insertXObjEChain;
 

package/lib/xObj-attr.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 {
   getXObjElement, insertXObjElement,
   // * import types definitions *
   INode,

package/lib/xObj-lib.d.ts

@@ -1,196 +1,102 @@
 /**
- * A result of `evalKeyName` function
+ * A `Node`-element
+ * @since 0.3.2
  */
-export type IEvalKeyNameResult = IEvalKeyNameResultOnSuccess | IEvalKeyNameResultOnFail;
-export const IEvalKeyNameResult: IEvalKeyNameResult;
 export type INode = {
     [x: string]: any;
 };
 export const INode: INode;
 /**
- * A result of an xObj modification ops
- */
-export type INodeModifResult = INodeModifResultOnFail | INodeModifResultOnSuccess;
-export const INodeModifResult: INodeModifResult;
-/**
- * Some conditions applied to an element as a result of an element name pattern
- * evaluation ops.
- */
-export type XObjENameDescrConditions = {
-    /**
-     * - element name
-     */
-    name: any;
-    /**
-     * - element type
-     */
-    type: any;
-    /**
-     * - some value
-     */
-    value?: any;
-};
-/**
- * A result of an element name pattern evaluation ops.
+ * A result of an xObj modification ops if failed
  */
-export type XObjENameDescr = {
-    /**
-     * - ops flag
-     */
-    isERR: boolean;
+export type INodeModifResultOnFail = {
     /**
-     * - element name
+     * - flag that indicates whether an ops is succeed or not
      */
-    name: null | number | string;
+    isSucceed: false;
     /**
-     * - some conditions applied to an element
+     * - some element as a result
      */
-    conditions: XObjENameDescrConditions | null;
-};
-/**
- * A list of a `INode`-elements
- */
-export type INodeList = INode[];
-/**
- * An options for an element insertion ops
- */
-export type OPT_inselops_L = {
-    force?: boolean;
-    ripOldies?: boolean;
-    acceptIfList?: boolean;
-};
-/**
- * An options for an element insertion ops
- */
-export type OPT_inselops_S = {
-    force?: boolean;
-    ripOldies?: boolean;
+    item: null;
 };
+export const INodeModifResultOnFail: INodeModifResultOnFail;
 /**
- * A result of a value check ops.
- * @deprecated
- * @todo \[from v0.3.0] make obsolete. Use `IEvalKeyNameReasonOnFail` instead.
+ * A result of an xObj modification ops if succeed (when child element returned)
  */
-export type RVAL_reason = {
+export type INodeModifResultOnSuccess_S1 = {
     /**
-     * - message ID
+     * - flag that indicates whether an ops is succeed or not
      */
-    code: string;
+    isSucceed: true;
     /**
-     * - message text
+     * - some element as a result
      */
-    msg: string;
+    item: INode;
 };
+export const INodeModifResultOnSuccess_S1: INodeModifResultOnSuccess_S1;
 /**
- * An error description of a value check ops on fail.
+ * A result of an xObj modification ops if succeed (when child element returned)
  */
-export type IEvalKeyNameReasonOnFail = {
+export type INodeModifResultOnSuccess_S2 = {
     /**
-     * - message ID
+     * - flag that indicates whether an ops is succeed or not
      */
-    code: string;
+    isSucceed: true;
     /**
-     * - message text
+     * - some element as a result
      */
-    msg: string;
+    item: INode[];
 };
+export const INodeModifResultOnSuccess_S2: INodeModifResultOnSuccess_S2;
 /**
- * A result of a value check ops.
- * @deprecated
- * @todo \[from v0.3.0] make obsolete. Use `IEvalKeyNameResult` instead.
+ * A result of an xObj modification ops if succeed (when child element not returned)
  */
-export type VCOR_evalkname = {
+export type INodeModifResultOnSuccess_S0 = {
     /**
-     * - ops flag
+     * - flag that indicates whether an ops is succeed or not
      */
-    isSucceed: boolean;
+    isSucceed: true;
     /**
-     * - result value or reson if failed
+     * - some element as a result
      */
-    value: string | IEvalKeyNameReasonOnFail;
+    item: null;
 };
+export const INodeModifResultOnSuccess_S0: INodeModifResultOnSuccess_S0;
 /**
- * An options setting for `evalKeyName` function
+ * A list of a `Node`-elements
  */
-export type IEvalKeyNameOptions = {
-    /**
-     * - a flag to accept only a non-empty string values
-     */
-    onlyNES?: boolean;
-};
+export type INodeList = INode[];
 /**
- * A result of `evalKeyName` function if succeed
+ * A result of an xObj modification ops
+ * @since 0.4.0
  */
-export type IEvalKeyNameResultOnSuccess = {
-    /**
-     * - ops flag
-     */
-    isSucceed: true;
-    /**
-     * - result value
-     */
-    value: string;
-};
+export type IAddNodeResult = INodeModifResultOnFail | INodeModifResultOnSuccess_S1;
 /**
- * A result of `evalKeyName` function if failed
+ * An options for an element insertion ops
  */
-export type IEvalKeyNameResultOnFail = {
-    /**
-     * - ops flag
-     */
-    isSucceed: false;
-    /**
-     * - reason of fail
-     */
-    value: IEvalKeyNameReasonOnFail;
+export type OPT_inselops_L = {
+    force?: boolean;
+    ripOldies?: boolean;
+    acceptIfList?: boolean;
 };
 /**
  * A result of an xObj modification ops
- * @deprecated
- * @todo \[from v0.3.2] make obsolete. Use `INodeModifResult` instead.
+ * @since 0.4.0
  */
-export type RVAL_emodif = {
-    /**
-     * - flag that indicates whether an ops is succeed or not
-     */
-    isSucceed: boolean;
-    /**
-     * - some element as a result
-     */
-    item: object | object[] | null;
-};
+export type IInsertNodeResult = INodeModifResultOnFail | INodeModifResultOnSuccess_S1 | INodeModifResultOnSuccess_S2;
 /**
- * A result of an xObj modification ops if failed
+ * A result of an xObj modification ops
+ * @since 0.4.0
  */
-export type INodeModifResultOnFail = {
-    /**
-     * - flag that indicates whether an ops is succeed or not
-     */
-    isSucceed: false;
-    /**
-     * - some element as a result
-     */
-    item: null;
-};
+export type IDeleteNodeResult = INodeModifResultOnFail | INodeModifResultOnSuccess_S0 | INodeModifResultOnSuccess_S1 | INodeModifResultOnSuccess_S2;
 /**
- * A result of an xObj modification ops if succeed
+ * An options for an element insertion ops
  */
-export type INodeModifResultOnSuccess = {
-    /**
-     * - flag that indicates whether an ops is succeed or not
-     */
-    isSucceed: true;
-    /**
-     * - some element as a result
-     */
-    item: object | object[];
+export type OPT_inselops_S = {
+    force?: boolean;
+    ripOldies?: boolean;
 };
 
-/**
- * Tries to convert a value into an ID.
- * @inner
- */
-export function evalKeyName(value: any, opt?: boolean | IEvalKeyNameOptions): IEvalKeyNameResult;
 /**
  * Extracts an element from a given object by its key.
  * @throws {TypeError} if `obj` param is not an object
@@ -202,7 +108,7 @@ export function getXObjElement(obj: INode, name: string): any | null;
  * @throws {TypeError} if `obj` param is not an object
  * @see {@link addXObjElementEx} for param details
  */
-export function addXObjElement(...args: addXObjElementParams): object | null;
+export function addXObjElement(...args: addXObjElementParams): INode | null;
 type addXObjElementParams = Parameters<typeof addXObjElementEx>;
 /**
  * Adds an element addressed by its key to a given object.
@@ -210,13 +116,13 @@ type addXObjElementParams = Parameters<typeof addXObjElementEx>;
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
-export function addXObjElementEx(obj: INode, name: string): INodeModifResult;
+export function addXObjElementEx(obj: INode, name: string): IAddNodeResult;
 /**
  * Inserts an element addressed by its key into a given object.
  * @throws {TypeError} if `obj` param is not an object
  * @see {@link insertXObjElementEx} for param details
  */
-export function insertXObjElement(...args: insertXObjElementParams): object | null;
+export function insertXObjElement(...args: insertXObjElementParams): INode | INode[] | null;
 type insertXObjElementParams = Parameters<typeof insertXObjElementEx>;
 /**
  * Inserts an element addressed by its key into a given object.
@@ -224,7 +130,7 @@ type insertXObjElementParams = Parameters<typeof insertXObjElementEx>;
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
-export function insertXObjElementEx(obj: INode, name: string, opt?: OPT_inselops_L): INodeModifResult;
+export function insertXObjElementEx(obj: INode, name: string, opt?: OPT_inselops_L): IInsertNodeResult;
 /**
  * Deletes an element addressed by its key from a given object.
  * @throws {TypeError} if `obj` param is not an object
@@ -237,7 +143,7 @@ type deleteXObjElementParams = Parameters<typeof deleteXObjElementEx>;
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
-export function deleteXObjElementEx(obj: INode, name: string): INodeModifResult;
+export function deleteXObjElementEx(obj: INode, name: string): IDeleteNodeResult;
 /**
  * Renames an element addressed by its key.
  * @throws {TypeError} if `obj` param is not an object
@@ -245,21 +151,12 @@ export function deleteXObjElementEx(obj: INode, name: string): INodeModifResult;
  * @throws {EvalKeyNameError} if `value` param is not valid identifier
  */
 export function renameXObjElement(obj: INode, name?: string, value?: string): boolean;
-/**
- * Clears a given node
- * @throws {TypeError} if `node`-param is not an object or array
- */
-export function clearXObjNode(node: INode | INode[]): boolean;
-/**
- * Tries to convert a value into an ID.
- */
-export function evalXObjEName(value: any): null | number | string;
 /**
  * Inserts a list elements into a given object.
  * @throws {TypeError} if `obj` param is not an object
  * @see insertXObjEListEx
  */
-export function insertXObjEList(...args: insertXObjEListParams): object | object[] | null;
+export function insertXObjEList(...args: insertXObjEListParams): INode[] | null;
 type insertXObjEListParams = Parameters<typeof insertXObjEListEx>;
 /**
  * Inserts a list elements into a given object.
@@ -267,18 +164,22 @@ type insertXObjEListParams = Parameters<typeof insertXObjEListEx>;
  * @throws {TypeError} if `obj` param is not an object
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
-export function insertXObjEListEx(obj: INode, name: string, opt?: OPT_inselops_S): INodeModifResult;
+export function insertXObjEListEx(obj: INode, name: string, opt?: OPT_inselops_S): INodeModifResultOnFail | INodeModifResultOnSuccess_S2;
 /**
- * Tries to convert a value into an element name description.
+ * Inserts a chain of an elements into a given object.
+ * @throws {TypeError} if `obj` param is not an object
+ * @experimental
  */
-export function genXObjENameDescr(value: any): XObjENameDescr;
+export function insertXObjEChain(obj: INode, ...args: insertListOfElementsParams): any | null;
 /**
- * Inserts an elements into a given object.
- * @throws {TypeError} if `obj` param is not an object
+ * Clears a given node
+ * @throws {TypeError} if `node`-param is not an object or array
  */
-export function insertXObjElements(obj: object, ...args: any[]): number;
+export function clearXObjNode(node: INode | INode[]): boolean;
 /**
- * Inserts a chain of an elements into a given object.
+ * Inserts an elements into a given object.
  * @throws {TypeError} if `obj` param is not an object
+ * @experimental
  */
-export function insertXObjEChain(obj: object, ...args: any[]): any | null;
+export function insertXObjElements(obj: INode, ...args: insertListOfElementsParams): number;
+type insertListOfElementsParams = [ ...names: string[], options: OPT_inselops_L];