@ygracs/xobj-lib-js 0.2.5-b → 0.2.6-b

package/lib/xObj-lib.d.ts

@@ -1,301 +1,297 @@
-/**
- * A result of a value check ops.
- */
-export type RVAL_reason = {
-    /**
-     * - message ID
-     */
-    code: string;
-    /**
-     * - message text
-     */
-    msg: string;
-};
-/**
- * A result of a value check ops.
- */
-export type VCOR_evalkname = {
-    /**
-     * - ops flag
-     */
-    isSucceed: boolean;
-    /**
-     * - result value or reson if failed
-     */
-    value: (string | RVAL_reason);
-};
-/**
- * A result of an xObj modification ops
- */
-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;
-};
-/**
- * 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;
-};
-
-export const XOBJ_DEF_PARAM_TNAME: string;
-export const XOBJ_DEF_ATTR_TNAME: string;
-
-/**
- * Extracts a parameter 'AS IS' from a given object.
- * @throws {TypeError} if first param is not an object
- * @throws {TypeError} if third param is not a string
- */
-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
- */
-export function readXObjParam(obj: object, key?: string): string;
-/**
- * Extracts a parameter from a given object and returns it as a boolean.
- * @throws {TypeError} if first 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
- */
-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
- */
-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 {TypeError} if third param is not a string
- */
-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
- */
-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
- */
-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
- */
-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 {TypeError} if third param is not a string
- */
-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
- */
-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
- */
-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
- */
-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 {TypeError} if third param is not a string
- */
-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
- */
-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
- */
-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
- */
-export function writeXObjAttrAsIndex(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
- * @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
- */
-export function getXObjAttributes(obj: object, key?: string): object | null;
-/**
- * Checks whether an attribute is exists.
- * @throws {TypeError} if first param is not an object
- */
-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
- */
-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 {TypeError} if second param is not an object
- * @throws {TypeError} if third param is not an object
- */
-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 {TypeError} if second param is empty string or not a string at all
- */
-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 {TypeError} if second param is empty string or not a string at all
- */
-export function addXObjElement(obj: object, name: string): RVAL_emodif;
-/**
- * Inserts an element addressed by its key into a given object.
- * @throws {TypeError} if first param is not an object
- * @see insertXObjElementEx
- */
-export function insertXObjElement(...args: [obj: object, name: string, opt?: OPT_inselops_L]): object | null;
-/**
- * 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 {TypeError} if second param is empty string or not a string at all
- */
-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
- * @see deleteXObjElementEx
- */
-export function deleteXObjElement(...args: [obj: object, name: string]): boolean;
-/**
- * Deletes an element addressed by its key from a given object.
- * @throws {TypeError} if first param is not an object
- * @throws {TypeError} if second param is empty string or not a string at all
- */
-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 {TypeError} if second param is not a string
- * @throws {TypeError} if third param is not a string
- */
-export function renameXObjElement(obj: object, name?: string, value?: string): 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 first param is not an object
- * @see insertXObjEListEx
- */
-export function insertXObjEList(...args: [obj: object, name: string, opt?: OPT_inselops_S]): object | object[] | null;
-/**
- * Inserts a list elements into a given object.
- * @since 0.2.0
- * @throws {TypeError} if first param is not an object
- * @throws {TypeError} if second param is empty string or not a string at all
- */
-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): VCOR_evalkname;
-/**
- * Tries to convert a value into an element name description.
- */
-export function genXObjENameDescr(value: any): object;
-/**
- * Inserts an elements into a given object.
- * @throws {TypeError} if first 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
- */
-export function insertXObjEChain(obj: object, ...args: any[]): any | null;
+/**
+ * A result of a value check ops.
+ */
+export type RVAL_reason = {
+    /** - message ID */
+    code: string;
+    /** - message text */
+    msg: string;
+};
+/**
+ * A result of a value check ops.
+ */
+export type VCOR_evalkname = {
+    /** - ops flag */
+    isSucceed: boolean;
+    /** - result value or reson if failed */
+    value: string | RVAL_reason;
+};
+/**
+ * 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: object | null;
+};
+/**
+ * A result of an xObj modification ops
+ */
+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;
+};
+/**
+ * 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;
+};
+
+/**
+ * Extracts a parameter 'AS IS' from a given object.
+ * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if third param is not a string
+ */
+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
+ */
+export function readXObjParam(obj: object, key?: string): string;
+/**
+ * Extracts a parameter from a given object and returns it as a boolean.
+ * @throws {TypeError} if first 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
+ */
+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
+ */
+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 {TypeError} if third param is not a string
+ */
+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
+ */
+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
+ */
+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
+ */
+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 {TypeError} if third param is not a string
+ */
+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
+ */
+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
+ */
+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
+ */
+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 {TypeError} if third param is not a string
+ */
+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
+ */
+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
+ */
+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
+ */
+export function writeXObjAttrAsIndex(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
+ * @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
+ */
+export function getXObjAttributes(obj: object, key?: string): object | null;
+/**
+ * Checks whether an attribute is exists.
+ * @throws {TypeError} if first param is not an object
+ */
+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
+ */
+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 {TypeError} if second param is not an object
+ * @throws {TypeError} if third param is not an object
+ */
+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 {TypeError} if second param is empty string or not a string at all
+ */
+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 {TypeError} if second param is empty string or not a string at all
+ */
+export function addXObjElement(obj: object, name: string): RVAL_emodif;
+/**
+ * Inserts an element addressed by its key into a given object.
+ * @throws {TypeError} if first param is not an object
+ * @see insertXObjElementEx
+ */
+export function insertXObjElement(...args: [obj: object, name: string, opt?: OPT_inselops_L]): object | null;
+/**
+ * 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 {TypeError} if second param is empty string or not a string at all
+ */
+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
+ * @see deleteXObjElementEx
+ */
+export function deleteXObjElement(...args: [obj: object, name: string]): boolean;
+/**
+ * Deletes an element addressed by its key from a given object.
+ * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if second param is empty string or not a string at all
+ */
+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 {TypeError} if second param is not a string
+ * @throws {TypeError} if third param is not a string
+ */
+export function renameXObjElement(obj: object, name?: string, value?: string): 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 first param is not an object
+ * @see insertXObjEListEx
+ */
+export function insertXObjEList(...args: [obj: object, name: string, opt?: OPT_inselops_S]): object | object[] | null;
+/**
+ * Inserts a list elements into a given object.
+ * @since 0.2.0
+ * @throws {TypeError} if first param is not an object
+ * @throws {TypeError} if second param is empty string or not a string at all
+ */
+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): VCOR_evalkname;
+/**
+ * Tries to convert a value into an element name description.
+ */
+export function genXObjENameDescr(value: any): XObjENameDescr;
+/**
+ * Inserts an elements into a given object.
+ * @throws {TypeError} if first 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
+ */
+export function insertXObjEChain(obj: object, ...args: any[]): any | null;