@ygracs/xobj-lib-js 0.2.9-b.2 → 0.3.0

package/lib/xObj-lib.d.ts

@@ -1,4 +1,17 @@
 import type { EvalKeyNameError } from "./xObj-errors";
+/**
+ * An error description of a value check ops on fail.
+ */
+export type IEvalKeyNameReasonOnFail = {
+    /**
+     * - message ID
+     */
+    code: string;
+    /**
+     * - message text
+     */
+    msg: string;
+};
 /**
  * A result of a value check ops.
  */
@@ -19,7 +32,7 @@ export type IEvalKeyNameOptions = {
     /**
      * - a flag to accept only a non-empty string values
      */
-    onlyNES?: boolean | undefined;
+    onlyNES?: boolean;
 };
 /**
  * A result of `evalKeyName` function if succeed
@@ -45,7 +58,7 @@ export type IEvalKeyNameResultOnFail = {
     /**
      * - reason of fail
      */
-    value: RVAL_reason;
+    value: IEvalKeyNameReasonOnFail;
 };
 /**
  * A result of `evalKeyName` function
@@ -64,6 +77,24 @@ export type VCOR_evalkname = {
      */
     value: string | RVAL_reason;
 };
+/**
+ * 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.
  */
@@ -79,7 +110,7 @@ export type XObjENameDescr = {
     /**
      * - some conditions applied to an element
      */
-    conditions: object | null;
+    conditions: XObjENameDescrConditions | null;
 };
 /**
  * A result of an xObj modification ops
@@ -111,190 +142,198 @@ export type OPT_inselops_S = {
 };
 
 /**
- * Clears a given node
- * @throws {TypeError} if `node`-param is not an object or array
- */
-export function clearXObjNode(node: object | object[]): boolean;
-/**
- * Extracts a parameter 'AS IS' from a given object.
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
- */
-export function readXObjParamRaw(obj: object, key?: string): any;
-/**
- * Extracts a parameter from a given object and returns it as a string.
- * @throws {TypeError} if first param is not an object
+ * Adds an element addressed by its key to a given object.
+ * @since 0.3.0
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
-export function readXObjParam(obj: object, key?: string): string;
+export function addXObjElementEx(obj: object, name: string): RVAL_emodif;
 /**
  * Extracts a parameter from a given object and returns it as a boolean.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function readXObjParamAsBool(obj: object, defValue?: boolean, key?: string): boolean;
 /**
  * Extracts a parameter from a given object and returns it as a number.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function readXObjParamAsNum(obj: object, defValue?: number, key?: string): number;
-/**
- * Extracts a parameter from a given object and returns it as a string.
- * @throws {TypeError} if first 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;
 /**
  * Extracts a parameter from a given object and returns it as 'index' value.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function readXObjParamAsIndex(obj: object, key?: string): number;
-/**
- * Writes a parameter 'AS IS' into a given object.
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if third param is not valid identifier
- */
-export function writeXObjParamRaw(obj: object, 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 first param is not an object
- */
-export function writeXObjParam(obj: object, 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 first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function writeXObjParamAsBool(obj: object, 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 first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function writeXObjParamAsNum(obj: object, 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 first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function writeXObjParamAsIndex(obj: object, 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 first 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 an attribute 'AS IS' from a given object.
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
- */
-export function readXObjAttrRaw(obj: object, attr?: string, key?: string): any;
-/**
- * Extracts an attribute from a given object and returns it as a string.
- * @throws {TypeError} if first param is not an object
- */
-export function readXObjAttr(obj: object, attr: string, key?: string): string;
 /**
  * Extracts an attribute from a given object and returns it as a boolean.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function readXObjAttrAsBool(obj: object, attr: string, defValue?: boolean, key?: string): boolean;
 /**
  * Extracts an attribute from a given object and returns it as a number.
  * @returns {number}
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function readXObjAttrAsNum(obj: object, attr: string, defValue?: number, key?: string): number;
-/**
- * Extracts an attribute from a given object and returns it as a string.
- * @throws {TypeError} if first param is not an object
- * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
- */
-export function readXObjAttrEx(obj: object, attr: string, opt?: object, key?: string): string;
 /**
  * Extracts an attribute from a given object and returns it as 'index' value.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function readXObjAttrAsIndex(obj: object, attr: string, key?: string): number;
-/**
- * Writes a parameter into a given object.
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
- */
-export function writeXObjAttrRaw(obj: object, attr: string, value: any, key?: string): boolean;
-/**
- * Tries to convert a given value to a string and writes it as an attribute
- * into a given object.
- * @throws {TypeError} if first param is not an object
- */
-export function writeXObjAttr(obj: object, attr: string, value: any, key?: string): boolean;
 /**
  * Tries to convert a given value to a boolean and writes it as an attribute
  * into a given object.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function writeXObjAttrAsBool(obj: object, attr: string, value: any, defValue?: boolean, key?: string): boolean;
 /**
  * Tries to convert a given value to a number and writes it as an attribute
  * into a given object.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function writeXObjAttrAsNum(obj: object, attr: string, value: any, defValue?: number, key?: string): boolean;
 /**
  * Tries to convert a given value into an 'index' value and writes it
  * as an attribute into a given object.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function writeXObjAttrAsIndex(obj: object, attr: string, value: any, key?: string): boolean;
+/**
+ * Clears a given node
+ * @throws {TypeError} if `node`-param is not an object or array
+ */
+export function clearXObjNode(node: object | object[]): boolean;
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * 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 an attribute 'AS IS' from a given object.
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `attr` param is not valid identifier
+ */
+export function readXObjAttrRaw(obj: object, attr?: string, key?: string): any;
+/**
+ * Extracts an attribute from a given object and returns it as a string.
+ * @throws {TypeError} if `obj` param is not an object
+ */
+export function readXObjAttr(obj: object, attr: string, key?: string): string;
+/**
+ * Extracts an attribute 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 readXObjAttrEx(obj: object, attr: string, opt?: object, key?: string): string;
+/**
+ * Writes a parameter into a given object.
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `attr` param is not valid identifier
+ */
+export function writeXObjAttrRaw(obj: object, attr: string, value: any, key?: string): boolean;
+/**
+ * Tries to convert a given value to a string and writes it as an attribute
+ * into a given object.
+ * @throws {TypeError} if `obj` param is not an object
+ */
+export function writeXObjAttr(obj: object, attr: string, value: any, key?: string): boolean;
 /**
  * Tries to convert a given value to a string and writes it as an attribute
  * into a given object.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  * @todo [since `v0.2.1`] deprecate use of `opt` as `string`
  */
 export function writeXObjAttrEx(obj: object, attr: string, value: any, opt?: object, key?: string): boolean;
 /**
  * Extracts an attributes from a given object by its key.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function getXObjAttributes(obj: object, key?: string): object | null;
 /**
  * Checks whether an attribute is exists.
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `attr` param is not valid identifier
  */
 export function checkXObjAttribute(obj: object, attr?: string, key?: string): boolean;
 /**
  * Deletes an attribute addressed by a given name.
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `attr` param is not valid identifier
  */
 export function deleteXObjAttribute(obj: object, attr?: string, key?: string): boolean;
 /**
  * Renames an attribute addressed by a given name.
  * @since 0.2.0
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
- * @throws {EvalKeyNameError} if third param is not valid identifier
- * @throws {EvalKeyNameError} if forth param is not valid identifier
+ * @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
  */
 export function renameXObjAttribute(obj: object, attr?: string, value?: string, key?: string): boolean;
 /**
  * Extracts an element from a given object by its key.
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
 export function getXObjElement(obj: object, name: string): any | null;
 /**
  * Adds an element addressed by its key to a given object.
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @see {@link addXObjElementEx} for param details
  */
-export function addXObjElement(obj: object, name: string): RVAL_emodif;
+export function addXObjElement(...args: addXObjElementParams): object | null;
+type addXObjElementParams = Parameters<typeof addXObjElementEx>;
 /**
  * Inserts an element addressed by its key into a given object.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  * @see {@link insertXObjElementEx} for param details
  */
 export function insertXObjElement(...args: insertXObjElementParams): object | null;
@@ -302,28 +341,28 @@ type insertXObjElementParams = Parameters<typeof insertXObjElementEx>;
 /**
  * Inserts an element addressed by its key into a given object.
  * @since 0.2.0
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
 export function insertXObjElementEx(obj: object, name: string, opt?: OPT_inselops_L): RVAL_emodif;
 /**
  * Deletes an element addressed by its key from a given object.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  * @see {@link deleteXObjElementEx} for param details
  */
 export function deleteXObjElement(...args: deleteXObjElementParams): boolean;
 type deleteXObjElementParams = Parameters<typeof deleteXObjElementEx>;
 /**
  * Deletes an element addressed by its key from a given object.
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
 export function deleteXObjElementEx(obj: object, name: string): RVAL_emodif;
 /**
  * Renames an element addressed by its key.
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
- * @throws {EvalKeyNameError} if third param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `name` param is not valid identifier
+ * @throws {EvalKeyNameError} if `value` param is not valid identifier
  */
 export function renameXObjElement(obj: object, name?: string, value?: string): boolean;
 /**
@@ -332,7 +371,7 @@ export function renameXObjElement(obj: object, name?: string, value?: string): b
 export function evalXObjEName(value: any): null | number | string;
 /**
  * Inserts a list elements into a given object.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  * @see insertXObjEListEx
  */
 export function insertXObjEList(...args: insertXObjEListParams): object | object[] | null;
@@ -340,8 +379,8 @@ type insertXObjEListParams = Parameters<typeof insertXObjEListEx>;
 /**
  * Inserts a list elements into a given object.
  * @since 0.2.0
- * @throws {TypeError} if first param is not an object
- * @throws {EvalKeyNameError} if second param is not valid identifier
+ * @throws {TypeError} if `obj` param is not an object
+ * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
 export function insertXObjEListEx(obj: object, name: string, opt?: OPT_inselops_S): RVAL_emodif;
 /**
@@ -355,12 +394,12 @@ export function evalKeyName(value: any, opt?: boolean | IEvalKeyNameOptions): IE
 export function genXObjENameDescr(value: any): XObjENameDescr;
 /**
  * Inserts an elements into a given object.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function insertXObjElements(obj: object, ...args: any[]): number;
 /**
  * Inserts a chain of an elements into a given object.
- * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if `obj` param is not an object
  */
 export function insertXObjEChain(obj: object, ...args: any[]): any | null;
 export {}