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

package/lib/xObj-errors.js

@@ -0,0 +1,71 @@
+// [v0.1.003-20251229]
+
+// === module init block ===
+
+const {
+  isPlainObject,
+} = require('@ygracs/bsfoc-lib-js');
+
+// === module inner block ===
+
+// === module main block ===
+
+const XOBJ_TE_INVARG_EMSG = 'invalid argument';
+const XOBJ_TE_NOBJ_EMSG = `${XOBJ_TE_INVARG_EMSG} (an object expected)`;
+const XOBJ_TE_NOBJ_ECODE = 'ERR_XOBJ_NOBJ';
+const XOBJ_TE_NARR_EMSG = `${XOBJ_TE_INVARG_EMSG} (an array expected)`;
+const XOBJ_TE_NARR_ECODE = 'ERR_XOBJ_NARR';
+const XOBJ_TE_NSTR_EMSG = `${XOBJ_TE_INVARG_EMSG} (a string expected)`;
+const XOBJ_TE_NSTR_ECODE = 'ERR_XOBJ_NSTR';
+const XOBJ_TE_NPOBJ_EMSG = `${XOBJ_TE_INVARG_EMSG} (a plain object expected)`;
+const XOBJ_TE_NPOBJ_ECODE = 'ERR_XOBJ_NPOBJ';
+const XOBJ_TE_ANES_EMSG = '<attr_name> must be a non-empty string';
+const XOBJ_TE_ANES_ECODE = 'ERR_XOBJ_INVARG_ATTR';
+const XOBJ_TE_KNES_EMSG = '<key_name> must be a non-empty string';
+const XOBJ_TE_KNES_ECODE = 'ERR_XOBJ_INVARG_KEY';
+
+const XOBJ_ECODE_TABLE = {
+  XOBJ_TE_NOBJ_EMSG,
+  XOBJ_TE_NOBJ_ECODE,
+  XOBJ_TE_NARR_EMSG,
+  XOBJ_TE_NARR_ECODE,
+  XOBJ_TE_NSTR_EMSG,
+  XOBJ_TE_NSTR_ECODE,
+  XOBJ_TE_NPOBJ_EMSG,
+  XOBJ_TE_NPOBJ_ECODE,
+  XOBJ_TE_ANES_EMSG,
+  XOBJ_TE_ANES_ECODE,
+  XOBJ_TE_KNES_EMSG,
+  XOBJ_TE_KNES_ECODE,
+};
+module.exports.XOBJ_ECODE_TABLE = XOBJ_ECODE_TABLE;
+
+/**
+ * @augments TypeError
+ * @classdesc Extends a base `TypeError` object to provide some information
+ *            on the errors thrown when a key name evaluation failed
+ */
+class EvalKeyNameError extends TypeError {
+  /**
+   * Creates a new instance
+   * @param {string} msg - some user error message
+   * @param {*} [options] - user options
+   */
+  constructor(msg, options) {
+    super(msg, options);
+    /** @type {string} */
+    this.name = 'EvalKeyNameError';
+    const code = (
+      isPlainObject(options) && typeof options.code === 'string'
+      ? options.code
+      : ''
+    );
+    /**
+     * Represents an error code
+     * @type {string}
+     */
+    this.code = code;
+  }
+
+};
+module.exports.EvalKeyNameError = EvalKeyNameError;

package/lib/xObj-lib.d.ts

@@ -0,0 +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 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;