smsmslib 1.0.79 → 1.0.81

package/javascr/util/deepwalk.js

@@ -1,5 +1,7 @@
 /**
  * @file
+ * Provides utility functions for **non-recursive deep traversal** of objects and
+ * arrays.
  *
  * @module javascr/system/deepwalk
  */
@@ -8,12 +10,73 @@
  * 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;
@@ -39,7 +102,30 @@ export function sj_deep_walk(value, i_depth, f_cb, user)
 }
 
 
-
+/**
+ * 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;
@@ -57,7 +143,7 @@ function deep_walk_cb(ao_TreeStack, from_child, o_user)
     b_continue &&= (!!o_TreeStack.child);
   }
 
-  if (b_continue && (o_TreeStack.i_child === 0))
+  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);
   }
@@ -65,7 +151,27 @@ function deep_walk_cb(ao_TreeStack, from_child, o_user)
   return b_continue;
 }
 
-// return path to ao_TreeStack[tail]
+
+/**
+ * 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);

package/javascr/util/index.js

@@ -12,6 +12,7 @@ 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/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.79",
+  "version": "1.0.81",
   "description": "Reusable functions for me.",
   "files": [
     "javascr/**/*.js",
@@ -19,6 +19,6 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "smsmslib": "^1.0.79"
+    "smsmslib": "^1.0.81"
   }
 }