@ygracs/xobj-lib-js 0.3.1 → 0.3.3

package/lib/xObj-lib.d.ts

@@ -1,8 +1,77 @@
-import type { EvalKeyNameError } from "./xObj-errors";
 /**
- * An error description of a value check ops on fail.
+ * A result of `evalKeyName` function
  */
-export type IEvalKeyNameReasonOnFail = {
+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.
+ */
+export type XObjENameDescr = {
+    /**
+     * - ops flag
+     */
+    isERR: boolean;
+    /**
+     * - element name
+     */
+    name: null | number | string;
+    /**
+     * - some conditions applied to an element
+     */
+    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;
+};
+/**
+ * A result of a value check ops.
+ * @deprecated
+ * @todo \[from v0.3.0] make obsolete. Use `IEvalKeyNameReasonOnFail` instead.
+ */
+export type RVAL_reason = {
     /**
      * - message ID
      */
@@ -13,9 +82,9 @@ export type IEvalKeyNameReasonOnFail = {
     msg: string;
 };
 /**
- * A result of a value check ops.
+ * An error description of a value check ops on fail.
  */
-export type RVAL_reason = {
+export type IEvalKeyNameReasonOnFail = {
     /**
      * - message ID
      */
@@ -25,6 +94,21 @@ export type RVAL_reason = {
      */
     msg: string;
 };
+/**
+ * A result of a value check ops.
+ * @deprecated
+ * @todo \[from v0.3.0] make obsolete. Use `IEvalKeyNameResult` instead.
+ */
+export type VCOR_evalkname = {
+    /**
+     * - ops flag
+     */
+    isSucceed: boolean;
+    /**
+     * - result value or reson if failed
+     */
+    value: string | IEvalKeyNameReasonOnFail;
+};
 /**
  * An options setting for `evalKeyName` function
  */
@@ -61,269 +145,58 @@ export type IEvalKeyNameResultOnFail = {
     value: IEvalKeyNameReasonOnFail;
 };
 /**
- * A result of `evalKeyName` function
- */
-export type IEvalKeyNameResult = IEvalKeyNameResultOnSuccess | IEvalKeyNameResultOnFail;
-/**
- * A result of a value check ops.
+ * A result of an xObj modification ops
+ * @deprecated
+ * @todo \[from v0.3.2] make obsolete. Use `INodeModifResult` instead.
  */
-export type VCOR_evalkname = {
+export type RVAL_emodif = {
     /**
-     * - ops flag
+     * - flag that indicates whether an ops is succeed or not
      */
     isSucceed: boolean;
     /**
-     * - result value or reson if failed
-     */
-    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
+     * - some element as a result
      */
-    value?: any;
+    item: object | object[] | null;
 };
 /**
- * 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;
+    item: null;
 };
 /**
- * A result of an xObj modification ops
+ * A result of an xObj modification ops if succeed
  */
-export type RVAL_emodif = {
+export type INodeModifResultOnSuccess = {
     /**
      * - flag that indicates whether an ops is succeed or not
      */
-    isSucceed: boolean;
+    isSucceed: true;
     /**
      * - some element as a result
      */
-    item: object | object[] | null;
-};
-/**
- * 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: object | 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 addXObjElementEx(obj: object, name: string): RVAL_emodif;
-/**
- * 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;
-/**
- * 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;
-/**
- * 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;
-/**
- * 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;
-/**
- * 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;
-/**
- * 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;
-/**
- * Extracts an attribute from a given object and returns it as a boolean.
- * @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 `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 'index' value.
- * @throws {TypeError} if `obj` param is not an object
- */
-export function readXObjAttrAsIndex(obj: object, attr: string, key?: string): number;
-/**
- * Tries to convert a given value to a boolean and writes it as an attribute
- * into a given 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 `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 `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 `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 `obj` param is not an object
- */
-export function getXObjAttributes(obj: object, key?: string): object | null;
-/**
- * Checks whether an attribute is exists.
- * @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 `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 `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
+ * Tries to convert a value into an ID.
+ * @inner
  */
-export function renameXObjAttribute(obj: object, attr?: string, value?: string, key?: string): boolean;
+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
  * @throws {EvalKeyNameError} if `name` param is not valid identifier
  */
-export function getXObjElement(obj: object, name: string): any | null;
+export function getXObjElement(obj: INode, name: string): any | null;
 /**
  * Adds an element addressed by its key to a given object.
  * @throws {TypeError} if `obj` param is not an object
@@ -331,6 +204,13 @@ export function getXObjElement(obj: object, name: string): any | null;
  */
 export function addXObjElement(...args: addXObjElementParams): object | null;
 type addXObjElementParams = Parameters<typeof addXObjElementEx>;
+/**
+ * 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 addXObjElementEx(obj: INode, name: string): INodeModifResult;
 /**
  * Inserts an element addressed by its key into a given object.
  * @throws {TypeError} if `obj` param is not an object
@@ -344,7 +224,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: object, name: string, opt?: OPT_inselops_L): RVAL_emodif;
+export function insertXObjElementEx(obj: INode, name: string, opt?: OPT_inselops_L): INodeModifResult;
 /**
  * Deletes an element addressed by its key from a given object.
  * @throws {TypeError} if `obj` param is not an object
@@ -357,14 +237,19 @@ 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: object, name: string): RVAL_emodif;
+export function deleteXObjElementEx(obj: INode, name: string): INodeModifResult;
 /**
  * Renames an element addressed by its key.
  * @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;
+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.
  */
@@ -382,12 +267,7 @@ 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: object, name: string, opt?: OPT_inselops_S): RVAL_emodif;
-/**
- * Tries to convert a value into an ID.
- * @inner
- */
-export function evalKeyName(value: any, opt?: boolean | IEvalKeyNameOptions): IEvalKeyNameResult;
+export function insertXObjEListEx(obj: INode, name: string, opt?: OPT_inselops_S): INodeModifResult;
 /**
  * Tries to convert a value into an element name description.
  */
@@ -402,4 +282,3 @@ export function insertXObjElements(obj: object, ...args: any[]): number;
  * @throws {TypeError} if `obj` param is not an object
  */
 export function insertXObjEChain(obj: object, ...args: any[]): any | null;
-export {}