assign-gingerly 0.0.25 → 0.0.26

package/README.md

@@ -355,6 +355,115 @@ assignGingerly(div, {
 // All instances and readonly objects preserved
 ```
 
+## Example 3c - Method Calls with withMethods
+
+The `withMethods` option allows you to call methods as part of property assignment, which is particularly useful for DOM APIs like `classList` and `part`:
+
+```TypeScript
+import assignGingerly from 'assign-gingerly';
+
+const element = document.createElement('div');
+
+// Simple method calls
+assignGingerly(element, {
+  '?.classList?.add': 'myClass',
+  '?.part?.add': 'myPart'
+}, { withMethods: ['add'] });
+
+console.log(element.classList.contains('myClass')); // true
+console.log(element.part.contains('myPart'));       // true
+```
+
+**How it works:**
+
+When a path segment matches a name in the `withMethods` array/set:
+- If it's the **last segment**: the method is called with the RHS value as an argument
+- If it's a **middle segment** and the next segment is also a method: called with no arguments
+- If it's a **middle segment** and the next segment is NOT a method: called with the next segment as a string argument
+- If the property is not a function: silently skipped
+
+**Array arguments:**
+
+Arrays are spread as multiple arguments:
+
+```TypeScript
+assignGingerly(element, {
+  '?.setAttribute': ['data-id', '123']
+}, { withMethods: ['setAttribute'] });
+
+// Equivalent to: element.setAttribute('data-id', '123')
+```
+
+**Chained method calls:**
+
+Methods can be chained to navigate through object hierarchies:
+
+```TypeScript
+const elementRef = {
+  deref() { return this.element; },
+  element: document.createElement('div')
+};
+
+assignGingerly(elementRef, {
+  '?.deref?.classList?.add': 'active'
+}, { withMethods: ['deref', 'add'] });
+
+// Equivalent to: elementRef.deref().classList.add('active')
+```
+
+**Complex chaining:**
+
+```TypeScript
+const shadowRoot = {
+  querySelector(selector) {
+    return this.elements[selector];
+  },
+  elements: {
+    'my-element': document.createElement('div')
+  }
+};
+
+assignGingerly(shadowRoot, {
+  '?.querySelector?.my-element?.classList?.add': 'highlighted'
+}, { withMethods: ['querySelector', 'add'] });
+
+// Equivalent to: shadowRoot.querySelector('my-element').classList.add('highlighted')
+```
+
+**Using Set for withMethods:**
+
+For better performance with many methods, use a Set:
+
+```TypeScript
+const methods = new Set(['add', 'remove', 'toggle', 'setAttribute']);
+
+assignGingerly(element, {
+  '?.classList?.add': 'class1',
+  '?.classList?.remove': 'class2',
+  '?.setAttribute': ['data-value', '42']
+}, { withMethods: methods });
+```
+
+**Mixing methods and normal assignments:**
+
+```TypeScript
+assignGingerly(element, {
+  '?.classList?.add': 'active',
+  '?.dataset?.userId': '123',
+  '?.style?.height': '100px'
+}, { withMethods: ['add'] });
+
+// classList.add() is called
+// dataset.userId and style.height are assigned normally
+```
+
+**Benefits:**
+
+- Cleaner syntax for DOM manipulation
+- Works with any object methods, not just DOM APIs
+- Silent failure for non-existent methods (garbage in, garbage out)
+- Supports method chaining and complex navigation patterns
+
 While we are in the business of passing values of object A into object B, we might as well add some extremely common behavior that allows updating properties of object B based on the current values of object B -- things like incrementing, toggling, and deleting.  Deleting is critical for assignTentatively, but is included with both functions.
 
 ## Example 4 - Incrementing values with += command

package/assignGingerly.js

@@ -270,6 +270,55 @@ function isClassInstance(value) {
     // Plain objects have Object.prototype or null as prototype
     return proto !== Object.prototype && proto !== null;
 }
+/**
+ * Helper function to evaluate a nested path with method calls
+ * Handles chained method calls where path segments can be methods
+ */
+function evaluatePathWithMethods(target, pathParts, value, withMethods) {
+    let current = target;
+    let i = 0;
+    // Process all segments except the last one
+    while (i < pathParts.length - 1) {
+        const part = pathParts[i];
+        const nextPart = pathParts[i + 1];
+        if (withMethods.has(part)) {
+            const method = current[part];
+            if (typeof method === 'function') {
+                // Check if next part is also a method
+                if (withMethods.has(nextPart)) {
+                    // Both are methods - call first with no args
+                    current = method.call(current);
+                }
+                else {
+                    // Only current is method - call with next part as string arg
+                    current = method.call(current, nextPart);
+                    i++; // Skip next part since we consumed it as argument
+                }
+            }
+            else {
+                // Not a function - just access property (create if needed)
+                if (!(part in current) || typeof current[part] !== 'object' || current[part] === null) {
+                    current[part] = {};
+                }
+                current = current[part];
+            }
+        }
+        else {
+            // Not a method - normal property access (create if needed)
+            if (!(part in current) || typeof current[part] !== 'object' || current[part] === null) {
+                current[part] = {};
+            }
+            current = current[part];
+        }
+        i++;
+    }
+    const lastKey = pathParts[pathParts.length - 1];
+    return {
+        target: current,
+        lastKey,
+        isMethod: withMethods.has(lastKey)
+    };
+}
 /**
  * Main assignGingerly function
  */
@@ -277,6 +326,12 @@ export function assignGingerly(target, source, options) {
     if (!target || typeof target !== 'object') {
         return target;
     }
+    // Convert withMethods array to Set for O(1) lookup
+    const withMethodsSet = options?.withMethods
+        ? options.withMethods instanceof Set
+            ? options.withMethods
+            : new Set(options.withMethods)
+        : undefined;
     const registry = options?.registry instanceof EnhancementRegistry
         ? options.registry
         : options?.registry
@@ -437,32 +492,86 @@ export function assignGingerly(target, source, options) {
         }
         if (isNestedPath(key)) {
             const pathParts = parsePath(key);
-            const lastKey = pathParts[pathParts.length - 1];
-            const parent = ensureNestedPath(target, pathParts);
-            if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-                // Check if property exists and is readonly OR is a class instance
-                if (lastKey in parent && (isReadonlyProperty(parent, lastKey) || isClassInstance(parent[lastKey]))) {
-                    // Property is readonly or a class instance - check if current value is an object
-                    const currentValue = parent[lastKey];
-                    if (typeof currentValue !== 'object' || currentValue === null) {
-                        throw new Error(`Cannot merge object into ${isReadonlyProperty(parent, lastKey) ? 'readonly ' : ''}primitive property '${String(lastKey)}'`);
+            // Check if we need to handle methods
+            if (withMethodsSet) {
+                const result = evaluatePathWithMethods(target, pathParts, value, withMethodsSet);
+                if (result.isMethod) {
+                    // Last segment is a method - call it
+                    const method = result.target[result.lastKey];
+                    if (typeof method === 'function') {
+                        if (Array.isArray(value)) {
+                            method.apply(result.target, value);
+                        }
+                        else {
+                            method.call(result.target, value);
+                        }
                     }
-                    // Recursively apply assignGingerly to the readonly object or class instance
-                    assignGingerly(currentValue, value, options);
+                    // Silently skip if not a function
+                    continue;
                 }
-                else {
-                    // Property is writable and not a class instance - normal recursive merge
-                    if (!(lastKey in parent) || typeof parent[lastKey] !== 'object') {
-                        parent[lastKey] = {};
+                // Not a method - proceed with normal assignment using evaluated target
+                const lastKey = result.lastKey;
+                const parent = result.target;
+                if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                    // Check if property exists and is readonly OR is a class instance
+                    if (lastKey in parent && (isReadonlyProperty(parent, lastKey) || isClassInstance(parent[lastKey]))) {
+                        const currentValue = parent[lastKey];
+                        if (typeof currentValue !== 'object' || currentValue === null) {
+                            throw new Error(`Cannot merge object into ${isReadonlyProperty(parent, lastKey) ? 'readonly ' : ''}primitive property '${String(lastKey)}'`);
+                        }
+                        assignGingerly(currentValue, value, options);
+                    }
+                    else {
+                        // Property is writable and not a class instance - replace it
+                        parent[lastKey] = value;
                     }
-                    assignGingerly(parent[lastKey], value, options);
+                }
+                else {
+                    parent[lastKey] = value;
                 }
             }
             else {
-                parent[lastKey] = value;
+                // No withMethods - use original logic
+                const lastKey = pathParts[pathParts.length - 1];
+                const parent = ensureNestedPath(target, pathParts);
+                if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                    // Check if property exists and is readonly OR is a class instance
+                    if (lastKey in parent && (isReadonlyProperty(parent, lastKey) || isClassInstance(parent[lastKey]))) {
+                        // Property is readonly or a class instance - check if current value is an object
+                        const currentValue = parent[lastKey];
+                        if (typeof currentValue !== 'object' || currentValue === null) {
+                            throw new Error(`Cannot merge object into ${isReadonlyProperty(parent, lastKey) ? 'readonly ' : ''}primitive property '${String(lastKey)}'`);
+                        }
+                        // Recursively apply assignGingerly to the readonly object or class instance
+                        assignGingerly(currentValue, value, options);
+                    }
+                    else {
+                        // Property is writable and not a class instance - replace it
+                        parent[lastKey] = value;
+                    }
+                }
+                else {
+                    parent[lastKey] = value;
+                }
             }
         }
         else {
+            // Non-nested path
+            // Check if this is a method call
+            if (withMethodsSet && withMethodsSet.has(key)) {
+                const method = target[key];
+                if (typeof method === 'function') {
+                    if (Array.isArray(value)) {
+                        method.apply(target, value);
+                    }
+                    else {
+                        method.call(target, value);
+                    }
+                }
+                // Silently skip if not a function
+                continue;
+            }
+            // Normal assignment
             if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
                 // Check if property exists and is readonly OR is a class instance
                 if (key in target && (isReadonlyProperty(target, key) || isClassInstance(target[key]))) {
@@ -475,7 +584,7 @@ export function assignGingerly(target, source, options) {
                     assignGingerly(currentValue, value, options);
                 }
                 else {
-                    // Property is writable and not a class instance - simple assignment
+                    // Property is writable and not a class instance - replace it
                     target[key] = value;
                 }
             }

package/assignGingerly.ts

@@ -35,6 +35,31 @@ export interface ItemscopeManagerConfig<T = any> {
 export interface IAssignGingerlyOptions {
   registry?: typeof EnhancementRegistry | EnhancementRegistry;
   bypassChecks?: boolean;
+  
+  /**
+   * List of property names that should be treated as methods to call
+   * rather than properties to assign.
+   * 
+   * When a path segment matches a name in this array/set:
+   * - If the property is a function, call it with appropriate arguments
+   * - For the last segment: use RHS value as argument (spread if array)
+   * - For middle segments: use next segment as string argument (if next is not also a method)
+   * - If consecutive segments are both methods, first is called with no arguments
+   * - If the property is not a function, silently skip
+   * 
+   * Example:
+   * assignGingerly(element, {
+   *   '?.classList?.add': 'myClass'
+   * }, { withMethods: ['add'] });
+   * // Calls: element.classList.add('myClass')
+   * 
+   * Chained methods:
+   * assignGingerly(elementRef, {
+   *   '?.deref?.querySelector?.myElement?.classList?.add': 'active'
+   * }, { withMethods: ['deref', 'querySelector', 'add'] });
+   * // Calls: elementRef.deref().querySelector('myElement').classList.add('active')
+   */
+  withMethods?: string[] | Set<string>;
 }
 
 /**
@@ -340,6 +365,62 @@ function isClassInstance(value: any): boolean {
   return proto !== Object.prototype && proto !== null;
 }
 
+/**
+ * Helper function to evaluate a nested path with method calls
+ * Handles chained method calls where path segments can be methods
+ */
+function evaluatePathWithMethods(
+  target: any,
+  pathParts: string[],
+  value: any,
+  withMethods: Set<string>
+): { target: any; lastKey: string; isMethod: boolean } {
+  let current = target;
+  let i = 0;
+  
+  // Process all segments except the last one
+  while (i < pathParts.length - 1) {
+    const part = pathParts[i];
+    const nextPart = pathParts[i + 1];
+    
+    if (withMethods.has(part)) {
+      const method = current[part];
+      if (typeof method === 'function') {
+        // Check if next part is also a method
+        if (withMethods.has(nextPart)) {
+          // Both are methods - call first with no args
+          current = method.call(current);
+        } else {
+          // Only current is method - call with next part as string arg
+          current = method.call(current, nextPart);
+          i++; // Skip next part since we consumed it as argument
+        }
+      } else {
+        // Not a function - just access property (create if needed)
+        if (!(part in current) || typeof current[part] !== 'object' || current[part] === null) {
+          current[part] = {};
+        }
+        current = current[part];
+      }
+    } else {
+      // Not a method - normal property access (create if needed)
+      if (!(part in current) || typeof current[part] !== 'object' || current[part] === null) {
+        current[part] = {};
+      }
+      current = current[part];
+    }
+    
+    i++;
+  }
+  
+  const lastKey = pathParts[pathParts.length - 1];
+  return {
+    target: current,
+    lastKey,
+    isMethod: withMethods.has(lastKey)
+  };
+}
+
 /**
  * Main assignGingerly function
  */
@@ -352,6 +433,13 @@ export function assignGingerly(
     return target;
   }
 
+  // Convert withMethods array to Set for O(1) lookup
+  const withMethodsSet = options?.withMethods
+    ? options.withMethods instanceof Set
+      ? options.withMethods
+      : new Set(options.withMethods)
+    : undefined;
+
   const registry = options?.registry instanceof EnhancementRegistry
     ? options.registry
     : options?.registry
@@ -524,30 +612,85 @@ export function assignGingerly(
 
     if (isNestedPath(key)) {
       const pathParts = parsePath(key);
-      const lastKey = pathParts[pathParts.length - 1];
-      const parent = ensureNestedPath(target, pathParts);
-
-      if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-        // Check if property exists and is readonly OR is a class instance
-        if (lastKey in parent && (isReadonlyProperty(parent, lastKey) || isClassInstance(parent[lastKey]))) {
-          // Property is readonly or a class instance - check if current value is an object
-          const currentValue = parent[lastKey];
-          if (typeof currentValue !== 'object' || currentValue === null) {
-            throw new Error(`Cannot merge object into ${isReadonlyProperty(parent, lastKey) ? 'readonly ' : ''}primitive property '${String(lastKey)}'`);
+      
+      // Check if we need to handle methods
+      if (withMethodsSet) {
+        const result = evaluatePathWithMethods(target, pathParts, value, withMethodsSet);
+        
+        if (result.isMethod) {
+          // Last segment is a method - call it
+          const method = result.target[result.lastKey];
+          if (typeof method === 'function') {
+            if (Array.isArray(value)) {
+              method.apply(result.target, value);
+            } else {
+              method.call(result.target, value);
+            }
           }
-          // Recursively apply assignGingerly to the readonly object or class instance
-          assignGingerly(currentValue, value, options);
-        } else {
-          // Property is writable and not a class instance - normal recursive merge
-          if (!(lastKey in parent) || typeof parent[lastKey] !== 'object') {
-            parent[lastKey] = {};
+          // Silently skip if not a function
+          continue;
+        }
+        
+        // Not a method - proceed with normal assignment using evaluated target
+        const lastKey = result.lastKey;
+        const parent = result.target;
+        
+        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+          // Check if property exists and is readonly OR is a class instance
+          if (lastKey in parent && (isReadonlyProperty(parent, lastKey) || isClassInstance(parent[lastKey]))) {
+            const currentValue = parent[lastKey];
+            if (typeof currentValue !== 'object' || currentValue === null) {
+              throw new Error(`Cannot merge object into ${isReadonlyProperty(parent, lastKey) ? 'readonly ' : ''}primitive property '${String(lastKey)}'`);
+            }
+            assignGingerly(currentValue, value, options);
+          } else {
+            // Property is writable and not a class instance - replace it
+            parent[lastKey] = value;
           }
-          assignGingerly(parent[lastKey], value, options);
+        } else {
+          parent[lastKey] = value;
         }
       } else {
-        parent[lastKey] = value;
+        // No withMethods - use original logic
+        const lastKey = pathParts[pathParts.length - 1];
+        const parent = ensureNestedPath(target, pathParts);
+
+        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+          // Check if property exists and is readonly OR is a class instance
+          if (lastKey in parent && (isReadonlyProperty(parent, lastKey) || isClassInstance(parent[lastKey]))) {
+            // Property is readonly or a class instance - check if current value is an object
+            const currentValue = parent[lastKey];
+            if (typeof currentValue !== 'object' || currentValue === null) {
+              throw new Error(`Cannot merge object into ${isReadonlyProperty(parent, lastKey) ? 'readonly ' : ''}primitive property '${String(lastKey)}'`);
+            }
+            // Recursively apply assignGingerly to the readonly object or class instance
+            assignGingerly(currentValue, value, options);
+          } else {
+            // Property is writable and not a class instance - replace it
+            parent[lastKey] = value;
+          }
+        } else {
+          parent[lastKey] = value;
+        }
       }
     } else {
+      // Non-nested path
+      
+      // Check if this is a method call
+      if (withMethodsSet && withMethodsSet.has(key)) {
+        const method = target[key];
+        if (typeof method === 'function') {
+          if (Array.isArray(value)) {
+            method.apply(target, value);
+          } else {
+            method.call(target, value);
+          }
+        }
+        // Silently skip if not a function
+        continue;
+      }
+      
+      // Normal assignment
       if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
         // Check if property exists and is readonly OR is a class instance
         if (key in target && (isReadonlyProperty(target, key) || isClassInstance(target[key]))) {
@@ -559,7 +702,7 @@ export function assignGingerly(
           // Recursively apply assignGingerly to the readonly object or class instance
           assignGingerly(currentValue, value, options);
         } else {
-          // Property is writable and not a class instance - simple assignment
+          // Property is writable and not a class instance - replace it
           target[key] = value;
         }
       } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.25",
+  "version": "0.0.26",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {

package/types/assign-gingerly/types.d.ts

@@ -169,6 +169,7 @@ export type IEnhancementRegistryItem<T = any> = EnhancementConfig<T>;
 export interface IAssignGingerlyOptions {
   registry?: typeof EnhancementRegistry | EnhancementRegistry;
   bypassChecks?: boolean;
+  withMethods?: string[] | Set<string>;
 }
 
 /**