smsmslib 1.0.78 → 1.0.80

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,245 @@
+/**
+ * @file
+ * Provides utility functions for **non-recursive deep traversal** of objects and
+ * arrays.
+ *
+ * @module javascr/system/deepwalk
+ */
+
+/** ---------------------------------------------------------------------------
+ * Imports.
+ * --------------------------------------------------------------------------- */
+
+import
+{
+  go_typeof,
+  sj_is_object,
+}
+from "./type.js";
+
+import
+{
+  sj_array_new,
+}
+from "./arraynew.js";
+
+import
+{
+  sj_array_push,
+}
+from "./arraypush.js";
+
+import
+{
+  sj_prop_get_own,
+  sj_prop_set_own,
+}
+from "./prop.js";
+
+import
+{
+  go_tree_walk_ret,
+  sj_tree_walk,
+}
+from "./tree.js";
+
+
+/** ---------------------------------------------------------------------------
+ * Functions.
+ * --------------------------------------------------------------------------- */
+
+/**
+ * Performs a deep traversal of an object or array.
+ *
+ * This function initiates a non-recursive tree walk starting from the given 
+ * `value`. It uses a stack-based approach to navigate through nested 
+ * properties up to a specified depth.
+ *
+ * @param {any} value [in]
+ * The root value to start the traversal from.
+ *
+ * @param {number} i_depth [in]
+ * The maximum depth to traverse (1-based). 
+ * If 1, only the root is visited. If 0, the traversal is unlimited.
+ *
+ * @param {function} f_cb [in]
+ * The user-defined callback function called at each node.
+ * Expected signature: `f_cb(ao_TreeStack, i_depth, user)`
+ * - ao_TreeStack: The current traversal stack.
+ * - i_depth: The maximum depth limit passed to `sj_deep_walk`.
+ * - user: The user data provided.
+ * Must return `true` to continue or `false` to abort.
+ *
+ * @param {any} user [in]
+ * Arbitrary user data passed to the callback function.
+ *
+ * @returns {number}
+ * Status code defined in `go_tree_walk_ret`. Same as `sj_tree_walk`.
+ * @see sj_tree_walk
+ */
+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;
+}
+
+
+/**
+ * Callback function for `sj_tree_walk` to perform a deep traversal of an object.
+ *
+ * This function serves two primary purposes:
+ * 1. **Node Adaptation**: It wraps the next child value into a node object 
+ * using `deep_walk_node_t` for the next step of traversal.
+ * 2. **User Callback Execution**: It triggers the user-provided callback 
+ * (`o_user.f_cb`) in "leading order".
+ *
+ * @param {object[]} ao_TreeStack [in]
+ * The stack of tree nodes representing the current traversal state.
+ *
+ * @param {boolean} from_child [in]
+ * Any information returning from a child node. (Unused)
+ *
+ * @param {object} o_user [in]
+ * A context object containing:
+ * - i_depth: Maximum traversal depth (1-based, 0 for unlimited).
+ * - f_cb   : The user-provided callback function to execute at each node.
+ * - user   : Arbitrary user data to pass to `f_cb`.
+ *
+ * @returns {boolean}
+ * true to continue the traversal; otherwise false to abort.
+ */
+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)) /* If leading order */
+  {
+    b_continue = o_user.f_cb(ao_TreeStack, o_user.i_depth, o_user.user);
+  }
+
+  return b_continue;
+}
+
+
+/**
+ * Retrieves the property path (array of keys/indices) leading to the current
+ * node in a deep traversal.
+ *
+ * This function reconstructs the path by iterating through the tree stack 
+ * from the root up to the parent of the current node. It is designed to be 
+ * called within a callback of `sj_deep_walk`.
+ * 
+ * Since the last element of `ao_TreeStack` represents the current node itself, 
+ * this function collects keys from all elements except the last to form the
+ * complete path.
+ *
+ * @param {object[]} ao_TreeStack [in]
+ * The stack of tree nodes representing the current traversal state.
+ *
+ * @returns {Array|null}
+ * An array of keys/indices representing the path to the current value; 
+ * otherwise null if the stack is invalid or an internal error occurs.
+ * Note: Returns an empty array if the current node is the root.
+ */ 
+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,8 @@ export * from "./arraynew.js";
 export * from "./arraypush.js";
 export * from "./arraysplice.js";
 export * from "./dataset.js";
+export * from "./deep.js";
+export * from "./deepwalk.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/javascr/util/tree.js

@@ -127,6 +127,8 @@ export const go_tree_walk_ret = Object.freeze(
  * - go_tree_walk_ret.i_noncb  : Provided f_cb is not a function.
  * - go_tree_walk_ret.i_stop   : Traversal was explicitly stopped by the callback.
  * - go_tree_walk_ret.i_nostack: Failed to allocate or push to the traversal stack.
+ * - go_tree_walk_ret.i_fatal  : Fatal error(not issued by this function, but should
+ *                               be handled by the caller).
  */
 export function sj_tree_walk(f_cb, root, user)
 {

package/package.json

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