smsmslib 1.0.78 → 1.0.79

package/javascr/util/array.js

@@ -197,3 +197,39 @@ export function sj_array_is_unique(a_src)
 }
 
 
+/**
+ * Normalizes an array subscript (index) to ensure it falls within the valid 
+ * range of [0, i_len - 1].
+ *
+ * This function supports circular indexing (wrap-around). For example, if i_len
+ * is 5, an index of 5 wraps around to 0, and an index of -1 wraps around to 4.
+ *
+ * @param {number} i_len [in]
+ * The length of the array or array-like object (e.g., string). 
+ * Must be a positive integer.
+ *
+ * @param {number} i_sub [in]
+ * The subscript (index) to be normalized.
+ *
+ * @returns {number}
+ * The normalized index within the range [0, i_len - 1].
+ * Returns -1 if i_len is 0 or negative.
+ */
+export function sj_subscript_norm(i_len, i_sub)
+{
+  let i_r = - 1;
+
+  if (0 < i_len)
+  {
+    i_r = i_sub % i_len;
+
+    if (i_r < 0)
+    {
+      i_r += i_len;
+    }
+  }
+
+  return i_r;
+}
+
+

package/javascr/util/deep.js

@@ -0,0 +1,116 @@
+/**
+ * @file
+ * Provides utility functions for **deeply nested property access and 
+ * modification** targeting an object's Own Properties.
+ *
+ * @module javascr/system/deep
+ */
+
+/** ---------------------------------------------------------------------------
+ * Imports.
+ * --------------------------------------------------------------------------- */
+
+import
+{
+  sj_prop_get_own,
+  sj_prop_set_own,
+  PropRet_t,
+}
+from "prop.js";
+
+
+/** ---------------------------------------------------------------------------
+ * Functions.
+ * --------------------------------------------------------------------------- */
+
+/**
+ * Updates the value of a deeply nested **own property** using an 
+ * array of keys.
+ *
+ * @param {any} dst [in]
+ * The root object or array to traverse.
+ *
+ * @param {(string|number)[]} a_prop [in]
+ * An array of property names or indices representing the path to the target. 
+ * Must not be empty. Each element must correspond to an existing own property, 
+ * and the final property must be writable.
+ *
+ * @param {any} value [in]
+ * The new value to assign to the target property.
+ *
+ * @returns {boolean}
+ * true if the traversal was successful and the target property was updated; 
+ * otherwise, false. Returns false if a_prop is empty or not an array.
+ */
+export function sj_deep_set_own(dst, a_prop, value)
+{
+  let dst_ref = dst;
+  let b_ok    = Array.isArray(a_prop) && (0 < a_prop.length);
+
+  for (let i_depth = 0; b_ok && (i_depth < a_prop.length); i_depth++)
+  {
+    const prop = a_prop[i_depth];
+
+    if (i_depth < (a_prop.length - 1))
+    {
+      const o_ret = sj_prop_get_own(dst_ref, prop);
+
+      b_ok = o_ret && o_ret.b_ok;
+      dst_ref = o_ret.value;
+    }
+    else
+    {
+      b_ok = sj_prop_set_own(dst_ref, prop, value);
+    }
+  }
+
+  return b_ok;
+}
+
+
+/**
+ * Retrieves a value from a deeply nested property using an array of keys.
+ *
+ * @param {any} src [in]
+ * The object, array, or array-like object to start the traversal.
+ *
+ * @param {(string|number)[]} a_prop [in]
+ * An array of property names or indices representing the path to the target 
+ * property. If this array is empty, the function returns the `src` itself 
+ * wrapped in PropRet_t.
+ *
+ * @returns {object|null}
+ * An instance of PropRet_t containing the following properties, or null 
+ * if the instance creation fails:
+ * - b_ok : true if the property value was retrieved successfully;
+ *          otherwise, false.
+ * - value: The retrieved property value if b_ok is true; otherwise, undefined.
+ * 
+ * Example:
+ * - If a_prop is empty: returns { b_ok: true, value: src }.
+ * - If successful: returns { b_ok: true, value: [found value] }.
+ * - If not found or invalid: returns { b_ok: false, value: undefined }.
+ */
+export function sj_deep_get_own(src, a_prop)
+{
+  let src_ref = src;
+  let b_ok    = Array.isArray(a_prop);
+  let o_ret   = PropRet_t(b_ok, src_ref);
+
+  b_ok = o_ret && o_ret.b_ok;
+
+  for (let i_depth = 0; b_ok && (i_depth < a_prop.length); i_depth++)
+  {
+    o_ret = sj_prop_get_own(src_ref, a_prop[i_depth]);
+    b_ok = o_ret && o_ret.b_ok;
+
+    if (b_ok)
+    {
+      src_ref = o_ret.value;
+    }
+  }
+
+  return o_ret;
+}
+
+

package/javascr/util/deepwalk.js

@@ -0,0 +1,139 @@
+/**
+ * @file
+ *
+ * @module javascr/system/deepwalk
+ */
+
+/** ---------------------------------------------------------------------------
+ * Imports.
+ * --------------------------------------------------------------------------- */
+
+
+
+/** ---------------------------------------------------------------------------
+ * Functions.
+ * --------------------------------------------------------------------------- */
+
+export function sj_deep_walk(value, i_depth, f_cb, user)
+{
+  let i_ret = go_tree_walk_ret.i_noncb;
+
+  if (typeof(f_cb) === go_typeof.s_function)
+  {
+    const o_user = sj_new_lit(() => ({i_depth, f_cb, user}));
+
+    i_ret = go_tree_walk_ret.i_fatal;
+
+    if (o_user)
+    {
+      const o_root = deep_walk_node_t(value);
+
+      if (o_root)
+      {
+        i_ret = sj_tree_walk(deep_walk_cb, o_root, o_user);
+      }
+    }
+  }
+
+  return i_ret;
+}
+
+
+
+function deep_walk_cb(ao_TreeStack, from_child, o_user)
+{
+  let   b_continue = true;
+  const b_depth = (o_user.i_depth < 1) || (ao_TreeStack.length <= o_user.i_depth);
+  const o_TreeStack = ao_TreeStack.at(- 1); /* tail */
+  const o_node      = o_TreeStack.node;
+
+  o_TreeStack.child = null;
+
+  if (b_depth && o_node.as_key && (o_TreeStack.i_child < o_node.as_key.length))
+  {
+    const s_key = o_node.as_key[o_TreeStack.i_child];
+
+    o_TreeStack.child = deep_walk_node_t(o_node.value[s_key]);
+    b_continue &&= (!!o_TreeStack.child);
+  }
+
+  if (b_continue && (o_TreeStack.i_child === 0))
+  {
+    b_continue = o_user.f_cb(ao_TreeStack, o_user.i_depth, o_user.user);
+  }
+
+  return b_continue;
+}
+
+// return path to ao_TreeStack[tail]
+export function sj_deep_path(ao_TreeStack)
+{
+  let   as_path = sj_array_new(0);
+  const b_arr = Array.isArray(ao_TreeStack);
+  let   b_ok = b_arr && (0 < ao_TreeStack.length) && (!!as_path);
+
+  for (let i_stk = 0; b_ok && (i_stk < ao_TreeStack.length - 1); i_stk++)
+  {
+    let   i_ret;
+    const o_TreeStack = ao_TreeStack[i_stk];
+    const o_ret = sj_deep_get_own(o_TreeStack, ["node", "as_key"]);
+
+    b_ok = false;
+
+    if ((!!o_ret) && o_ret.b_ok)
+    {
+      const as_key = o_ret.value;
+
+      if (as_key && (o_TreeStack.i_child < as_key.length))
+      {
+        i_ret = sj_array_push(as_path, as_key[o_TreeStack.i_child]);
+        b_ok = (0 < i_ret);
+      }
+    }
+  }
+
+  if (!b_ok)
+  {
+    as_path = null;
+  }
+
+  return as_path;
+}
+
+
+/**
+ * Creates a node object for deep traversal (tree walking).
+ *
+ * @param {any} value [in]
+ * The value to be wrapped in a node.
+ *
+ * @returns {object|null}
+ * A node object containing:
+ * - value  : The original value.
+ * - b_array: True if the value is an array.
+ * - as_key : An array of own property keys if the value is an object;
+ *            otherwise null.
+ * Returns null if the node object cannot be created.
+ */
+function deep_walk_node_t(value)
+{
+  let   o_node = null;
+  let   as_key = null;
+  const b_obj  = sj_is_object(value);
+
+  if (b_obj)
+  {
+    as_key = sj_keys(value);
+  }
+
+  if ((!b_obj) || as_key)
+  {
+    const b_array = Array.isArray(value);
+
+    o_node = sj_new_lit(() => ({value, b_array, as_key}));
+  }
+
+  return o_node;
+}
+
+

package/javascr/util/index.js

@@ -11,6 +11,7 @@ export * from "./arraynew.js";
 export * from "./arraypush.js";
 export * from "./arraysplice.js";
 export * from "./dataset.js";
+export * from "./deep.js";
 export * from "./document.js";
 export * from "./error.js";
 export * from "./html.js";

package/javascr/util/prop.js

@@ -254,10 +254,11 @@ export function sj_prop_set_own(o_any, prop, value)
  * The property name (non-empty string) or array index (non-negative integer) 
  * to retrieve.
  *
- * @returns {object}
- * A literal object (via sj_new_lit) containing:
- * - b_ok : true if the property exists as an own property.
- * - value: The value of the property if b_ok is true; otherwise, undefined.
+ * @returns {object|null}
+ * An instance of PropRet_t containing the following properties, or null 
+ * if the instance creation fails:
+ * - b_ok : true if the property exists as an own property; otherwise, false.
+ * - value: The retrieved property value if b_ok is true; otherwise, undefined.
  */
 export function sj_prop_get_own(o_any, prop)
 {
@@ -277,8 +278,8 @@ export function sj_prop_get_own(o_any, prop)
     }
   }
 
-  const s_lit = sj_new_lit(() => ({b_ok, value}));
-  return s_lit;
+  const o_ret = PropRet_t(b_ok, value);
+  return o_ret;
 }
 
 
@@ -297,8 +298,9 @@ export function sj_prop_get_own(o_any, prop)
  * The property name (non-empty string) or array index (non-negative integer) 
  * to delete.
  *
- * @returns {object}
- * A literal object containing:
+ * @returns {object|null}
+ * An instance of PropRet_t containing the following properties, or null 
+ * if the instance creation fails:
  * - b_ok : true if the property existed and was successfully deleted.
  * - value: The value of the property before deletion if b_ok is true; 
  *          otherwise, undefined.
@@ -324,8 +326,58 @@ export function sj_prop_delete_own(o_any, prop)
     }
   }
 
+  const o_ret = PropRet_t(b_ok, value);
+  return o_ret;
+}
+
+
+/**
+ * Creates a result object for property-related operations.
+ *
+ * @param {boolean} b_ok [in]
+ * True if the operation succeeded; otherwise, false.
+ *
+ * @param {any} value [in]
+ * The property value.
+ *
+ * @returns {object|null}
+ * A literal object containing the following properties, or null if the 
+ * creation fails:
+ * - b_ok : Same as the argument.
+ * - value: Same as the argument.
+ */
+export function PropRet_t(b_ok, value)
+{
   const s_lit = sj_new_lit(() => ({b_ok, value}));
+  
   return s_lit;
 }
 
 
+/**
+ * Retrieves an array of a given object's own enumerable property names.
+ *
+ * @param {any} any [in]
+ * The object whose enumerable own properties are to be returned.
+ *
+ * @returns {string[] | null}
+ * string[]: All the enumerable properties of the given object.
+ * null    : The input is not a valid object, or a runtime error occurred.
+ */
+export function sj_keys(any)
+{
+  let  as_key = null;
+
+  try
+  {
+    as_key = Object.keys(any);
+  }
+  catch (o_err)
+  {
+    console.error(`${sj_keys.name}: ${o_err.message}`);
+  }
+
+  return as_key;
+}
+
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smsmslib",
-  "version": "1.0.78",
+  "version": "1.0.79",
   "description": "Reusable functions for me.",
   "files": [
     "javascr/**/*.js",
@@ -19,6 +19,6 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "smsmslib": "^1.0.78"
+    "smsmslib": "^1.0.79"
   }
 }