smsmslib 1.0.76 → 1.0.77

package/javascr/util/dataset.js

@@ -175,7 +175,12 @@ export function sj_dataset_get_own(o_element, s_prop)
 
   if (o_element)
   {
-    s_value = sj_prop_get_own(o_element.dataset, s_prop);
+    const o_ret = sj_prop_get_own(o_element.dataset, s_prop);
+
+    if (o_ret.b_ok)
+    {
+      s_value = o_ret.value;
+    }
   }
 
   return s_value;
@@ -205,7 +210,12 @@ export function sj_dataset_delete_own(o_element, s_prop)
 
   if (o_element)
   {
-    value = sj_prop_delete_own(o_element.dataset, s_prop);
+    const o_ret = sj_prop_delete_own(o_element.dataset, s_prop);
+
+    if (o_ret.b_ok)
+    {
+      value = o_ret.value;
+    }
   }
 
   return value;

package/javascr/util/prop.js

@@ -12,7 +12,18 @@
  * Imports.
  * --------------------------------------------------------------------------- */
 
-import {sj_is_object, sj_is_primitive_text} from "./type.js";
+import
+{
+  sj_is_object,
+  sj_is_primitive_text,
+}
+from "./type.js";
+
+import
+{
+  sj_new_lit,
+}
+from "./new.js";
 
 
 /** ---------------------------------------------------------------------------
@@ -20,259 +31,301 @@ import {sj_is_object, sj_is_primitive_text} from "./type.js";
  * --------------------------------------------------------------------------- */
 
 /**
- * Safely updates the value of an **existing own data property** only if the new value
- * is different, and optionally records the previous value.
+ * Safely updates the value of an **existing own data property**
+ * (including array elements) only if the new value is different from the
+ * current one.
+ *
+ * This setting is performed only if the property already exists directly on the 
+ * target (ignoring the prototype chain), is writable, and the new value is 
+ * different (evaluated via Object.is). Optionally, the previous value can be 
+ * output to the o_chg argument. For arrays, this ensures that only 
+ * elements at existing indices are updated, preventing length expansion.
  *
  * @param {any} o_any [in]
- * The object whose property is to be changed.
+ * The object or array whose property/element is to be changed.
  *
- * @param {string} s_prop [in]
- * The name of the property (key). Must be a non-empty primitive string.
+ * @param {string|number} prop [in]
+ * The property name (non-empty string) or array index (non-negative integer).
  *
  * @param {any} value [in]
  * The new value to assign.
  *
- * @param {object} [o_chg] [out]
- * Optional. An object to store the previous value of the property if a change occurs.
+ * @param {object} o_chg [out]
+ * Optional. An object to store the previous value if a change occurs.
  *
  * @returns {boolean}
  * true  : The property was successfully updated with a different value.
- * false : No change was made (e.g., property is not writable, value is identical, 
- * or o_any is not a valid object).
- * The return value is guaranteed to be a primitive boolean.
+ * false : No change was made (e.g., property does not exist, is not writable, 
+ *         value is identical, or arguments are invalid).
  */
-export function sj_prop_chg_own(o_any, s_prop, value, o_chg)
+export function sj_prop_chg_own(o_any, prop, value, o_chg)
 {
-  const b_prop = sj_is_primitive_text(s_prop);
-  let   b_obj  = sj_is_object(o_any);
-  let   b_chg  = (b_obj && b_prop);
+  const b_obj  = sj_is_object(o_any);
+  const b_num  = Number.isInteger(prop);
+  const b_text = sj_is_primitive_text(prop);
+  let   b_ok   = b_obj && (b_text || (b_num && (0 <= prop)));
 
-  if (b_chg)
+  if (b_ok)
   {
-    const o_desc = Object.getOwnPropertyDescriptor(o_any, s_prop);
+    const o_desc = Object.getOwnPropertyDescriptor(o_any, prop);
 
-    b_chg = o_desc && o_desc.writable && (!Object.is(o_any[s_prop], value));
+    b_ok = o_desc && o_desc.writable && (!Object.is(o_any[prop], value));
 
-    if (b_chg)
+    if (b_ok)
     {
       if (o_chg)
       {
-        sj_prop_upsert_own(o_chg, s_prop, o_any[s_prop]);
+        sj_prop_upsert_own(o_chg, prop, o_any[prop]);
       }
 
-      o_any[s_prop] = value;
+      o_any[prop] = value;
     }
   }
 
-  return !!b_chg;
+  return !!b_ok;
 }
 
 
 /**
- * Safely adds a **new own property** to an object.
+ * Safely adds a **new own property** (including array elements) to an object
+ * or array.
  *
- * This function guarantees that the property will be created only if
- * it **does not already exist** on the object itself (it ignores the prototype chain).
- * If the property exists, the value is not overwritten.
+ * This function ensures that the setting is performed only if the property 
+ * does not already exist directly on the target (ignoring the prototype chain) 
+ * and the target is extensible. For arrays, this can be used to fill an 
+ * empty slot or add a new element at the end, provided the index is not 
+ * already occupied.
  *
  * @param {any} o_any [in]
- * The object to which the new property should be added.
+ * The object or array to which the new property or element should be added.
  *
- * @param {string} s_prop [in]
- * The name of the new property (key). Must be a non-empty primitive string.
+ * @param {string|number} prop [in]
+ * The property name (non-empty string) or array index (non-negative integer).
  *
  * @param {any} value [in]
- * The value to assign to the new property.
+ * The value to assign to the new property or element.
  *
  * @returns {boolean}
- * `true` if the new property was successfully added, otherwise `false`.
+ * true  : The new property/element was successfully added.
+ * false : No change was made (e.g., property already exists, object is not 
+ *         extensible, or arguments are invalid).
  */
-export function sj_prop_add_own_new(o_any, s_prop, value)
+export function sj_prop_add_own_new(o_any, prop, value)
 {
-  const b_obj   = sj_is_object(o_any);
-  const b_prop  = sj_is_primitive_text(s_prop);
-  let   b_added = (b_prop && b_obj);
+  const b_obj  = sj_is_object(o_any);
+  const b_num  = Number.isInteger(prop);
+  const b_text = sj_is_primitive_text(prop);
+  let   b_ok   = b_obj && (b_text || (b_num && (0 <= prop)));
 
-  if (b_added)
+  if (b_ok)
   {
-    b_added = !Object.hasOwn(o_any, s_prop);
+    b_ok = !Object.hasOwn(o_any, prop);
 
-    if (b_added)
+    if (b_ok)
     {
-      b_added = Object.isExtensible(o_any);
+      b_ok = Object.isExtensible(o_any);
     }
   }
 
-  if (b_added)
+  if (b_ok)
   {
-    o_any[s_prop] = value;
+    o_any[prop] = value;
   }
 
-  return !!b_added;
+  return b_ok;
 }
 
 
 /**
- * Safely performs Upsert (Update or Insert) for **own data properties** of an object,
- * explicitly excluding accessor properties.
+ * Safely performs an Upsert (Update or Insert) for **own data properties**
+ * (including array elements).
  *
- * This function exclusively targets properties directly owned by the object
- * (prototype chain is ignored).
+ * This setting is performed only if the property already exists and is writable, 
+ * or if the property does not exist but the object or array is extensible. 
+ * For arrays, this allows updating existing elements or adding new elements 
+ * (potentially expanding the length) as long as the array is not frozen or sealed.
  *
  * @param {any} o_any [in]
- * The object on which to perform the upsert operation.
+ * The object or array on which to perform the upsert operation.
  *
- * @param {string} s_prop [in]
- * The name of the property (key). Must be a non-empty primitive string.
+ * @param {string|number} prop [in]
+ * The property name (non-empty string) or array index (non-negative integer).
  *
  * @param {any} value [in]
  * The value to assign.
  *
  * @returns {boolean}
- * `true` if the assignment (update or insert) was successful, otherwise `false`.
+ * true : The property was successfully updated or inserted.
+ * false: No change was made (e.g., property is not writable, object is not 
+ *        extensible, or arguments are invalid).
  */
-export function sj_prop_upsert_own(o_any, s_prop, value)
+export function sj_prop_upsert_own(o_any, prop, value)
 {
-  const b_obj    = sj_is_object(o_any);
-  const b_prop   = sj_is_primitive_text(s_prop);
-  let   b_upsert = (b_obj && b_prop);
+  const b_obj  = sj_is_object(o_any);
+  const b_num  = Number.isInteger(prop);
+  const b_text = sj_is_primitive_text(prop);
+  let   b_ok   = b_obj && (b_text || (b_num && (0 <= prop)));
 
-  if (b_upsert)
+  if (b_ok)
   {
-    const o_desc = Object.getOwnPropertyDescriptor(o_any, s_prop);
+    const o_desc = Object.getOwnPropertyDescriptor(o_any, prop);
 
-    b_upsert = o_desc;
+    b_ok = o_desc;
 
-    if (b_upsert)
+    if (b_ok)
     {
-      b_upsert = o_desc.writable;
+      b_ok = o_desc.writable;
     }
     else
     {
-      b_upsert = Object.isExtensible(o_any);
+      // !freeze, !seal, and !preventExtensions
+      b_ok = Object.isExtensible(o_any);
     }
   }
 
-  if (b_upsert)
+  if (b_ok)
   {
-    o_any[s_prop] = value;
+    o_any[prop] = value;
   }
 
-  return !!b_upsert;
+  return !!b_ok;
 }
 
 
 /**
- * Safely sets (overwrites) the value of an **existing own data property** in an object.
+ * Safely sets (overwrites) the value of an **existing own data property**
+ * (including array elements).
  *
- * The assignment is executed only if the property exists on the object, and
- * its descriptor indicates that it is writable (`writable: true`).
+ * This setting is performed only if the property already exists directly 
+ * on the object or array (ignoring the prototype chain) and its descriptor 
+ * indicates that it is writable. For arrays, this ensures that only 
+ * elements at existing indices are updated, preventing unintended expansion 
+ * of the array length.
  *
  * @param {any} o_any [in]
- * The object to set the value in.
+ * The object or array to set the value in.
  *
- * @param {string} s_prop [in]
- * The name of the property (key) to set. Must be a non-empty primitive string.
+ * @param {string|number} prop [in]
+ * The property name (non-empty string) or array index (non-negative integer)
+ * to set.
  *
  * @param {any} value [in]
- * The value to assign to the property.
+ * The new value to assign to the property.
  *
  * @returns {boolean}
- * `true` if the own data property was successfully set (overwritten), otherwise `false`.
+ * true  : The own property existed and was successfully overwritten.
+ * false : No change was made (e.g., property does not exist, is not writable, 
+ *         or arguments are invalid).
  */
-export function sj_prop_set_own(o_any, s_prop, value)
+export function sj_prop_set_own(o_any, prop, value)
 {
   const b_obj  = sj_is_object(o_any);
-  const b_prop = sj_is_primitive_text(s_prop);
-  let   b_set  = (b_obj && b_prop);
+  const b_num  = Number.isInteger(prop);
+  const b_text = sj_is_primitive_text(prop);
+  let   b_ok   = b_obj && (b_text || (b_num && (0 <= prop)));
 
-  if (b_set)
+  if (b_ok)
   {
-    const o_desc = Object.getOwnPropertyDescriptor(o_any, s_prop);
+    const o_desc = Object.getOwnPropertyDescriptor(o_any, prop);
 
-    b_set = (o_desc && o_desc.writable);
+    b_ok = !!(o_desc && o_desc.writable);
 
-    if (b_set)
+    if (b_ok)
     {
-      o_any[s_prop] = value;
+      o_any[prop] = value;
     }
   }
 
-  return !!b_set;
+  return b_ok;
 }
 
 
 /**
- * Safely retrieves the value of an **own property** (non-inherited property)
- * from an object.
+ * Safely retrieves the value of an **own property** (including array elements) 
+ * from an object or array.
  *
- * This function only accesses properties directly defined on the object itself,
- * ignoring the prototype chain.
+ * This function only accesses properties directly defined on the target itself, 
+ * completely ignoring the prototype chain.
  *
  * @param {any} o_any [in]
- * The object (or any data) to retrieve the property from.
+ * The object or array to retrieve the property or element from.
  *
- * @param {string} s_prop [in]
- * The name of the property (key) to retrieve. Must be a non-empty primitive string.
+ * @param {string|number} prop [in]
+ * The property name (non-empty string) or array index (non-negative integer) 
+ * to retrieve.
  *
- * @returns {any}
- * The value of the property if it exists as an own property, or `undefined` if the
- * property does not exist on the object, or if the arguments are invalid.
+ * @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.
  */
-export function sj_prop_get_own(o_any, s_prop)
+export function sj_prop_get_own(o_any, prop)
 {
   let   value  = undefined;
   const b_obj  = sj_is_object(o_any);
-  const b_prop = sj_is_primitive_text(s_prop);
+  const b_num  = Number.isInteger(prop);
+  const b_text = sj_is_primitive_text(prop);
+  let   b_ok   = b_obj && (b_text || (b_num && (0 <= prop)));
 
-  if (b_obj && b_prop)
+  if (b_ok)
   {
-    const b_has = Object.hasOwn(o_any, s_prop);
+    const b_has = Object.hasOwn(o_any, prop);
 
     if (b_has)
     {
-      value = o_any[s_prop];
+      value = o_any[prop];
     }
   }
 
-  return value;
+  const s_lit = sj_new_lit(() => ({b_ok, value}));
+  return s_lit;
 }
 
 
 /**
- * Safely deletes an **own property** from an object and returns the deleted value.
+ * Safely deletes an **own property** (including array elements) and returns 
+ * the deleted value along with the success status.
  *
- * If the deletion succeeds, the value of the deleted property is returned.
- * If the deletion fails (e.g., property does not exist, configurable: false,
- * or invalid arguments), `undefined` is returned.
+ * This function targets properties directly defined on the object or array, 
+ * ignoring the prototype chain. If the target is an array, using this function 
+ * will create a "hole" (sparse array) at the specified index.
  *
  * @param {any} o_any [in]
- * The object from which to delete the property.
+ * The object or array from which to delete the property/element.
  *
- * @param {string} s_prop [in]
- * The name of the property (key) to delete. Must be a non-empty primitive string.
+ * @param {string|number} prop [in]
+ * The property name (non-empty string) or array index (non-negative integer) 
+ * to delete.
  *
- * @returns {any}
- * The value of the deleted property, or `undefined` if deletion failed.
+ * @returns {object}
+ * A literal object containing:
+ * - 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.
  */
-export function sj_prop_delete_own(o_any, s_prop)
+export function sj_prop_delete_own(o_any, prop)
 {
   let   value  = undefined;
   const b_obj  = sj_is_object(o_any);
-  const b_prop = sj_is_primitive_text(s_prop);
+  const b_num  = Number.isInteger(prop);
+  const b_text = sj_is_primitive_text(prop);
+  let   b_ok   = b_obj && (b_text || (b_num && (0 <= prop)));
 
-  if (b_obj && b_prop)
+  if (b_ok)
   {
-    const o_desc = Object.getOwnPropertyDescriptor(o_any, s_prop);
+    const o_desc = Object.getOwnPropertyDescriptor(o_any, prop);
+
+    b_ok = o_desc && o_desc.configurable;
 
-    if (o_desc && o_desc.configurable)
+    if (b_ok)
     {
-      value = o_any[s_prop];
-      delete o_any[s_prop];
+      value = o_any[prop];
+      delete o_any[prop];
     }
   }
 
-  return value;
+  const s_lit = sj_new_lit(() => ({b_ok, value}));
+  return s_lit;
 }
 
 

package/package.json

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