assign-gingerly 0.0.24 → 0.0.26

package/README.md

@@ -108,10 +108,40 @@ console.log(obj);
 // }
 ```
 
-When the right hand side of an expression is an object, assignGingerly is recursively applied (passing the third argument in if applicable, which will be discussed below).
+When the right hand side of an expression is an object, assignGingerly behavior depends on the context:
+- For **nested paths** (starting with `?.`): recursively merges into nested objects, creating them if needed
+- For **plain keys**: performs simple assignment (like `Object.assign`), unless the target property is readonly or a class instance (see Examples 3a and 3b below)
 
 Of course, just as Object.assign led to object spread notation, assignGingerly could lead to some sort of deep structural JavaScript syntax, but that is outside the scope of this polyfill package.
 
+## Example 3-plain - Plain Key Object Assignment
+
+For plain keys (without `?.` prefix), assignGingerly performs simple assignment, just like `Object.assign`:
+
+```TypeScript
+const obj = {};
+const template = document.createElement('template');
+template.innerHTML = '<div>Hello</div>';
+
+assignGingerly(obj, {
+    template: template,
+    config: { theme: 'dark', lang: 'en' }
+});
+
+console.log(obj.template === template); // true - direct assignment
+console.log(obj.config); // { theme: 'dark', lang: 'en' } - direct assignment
+```
+
+This is different from nested paths, which create intermediate objects:
+
+```TypeScript
+const obj = {};
+assignGingerly(obj, {
+    '?.config?.theme': 'dark'
+});
+console.log(obj.config); // { theme: 'dark' } - intermediate object created
+```
+
 ## Example 3a - Automatic Readonly Property Detection
 
 assignGingerly automatically detects readonly properties and merges into them instead of attempting to replace them. This makes working with DOM properties like `style` and `dataset` much more ergonomic:
@@ -325,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,11 +584,8 @@ export function assignGingerly(target, source, options) {
                     assignGingerly(currentValue, value, options);
                 }
                 else {
-                    // Property is writable and not a class instance - normal recursive merge
-                    if (!(key in target) || typeof target[key] !== 'object') {
-                        target[key] = {};
-                    }
-                    assignGingerly(target[key], value, options);
+                    // Property is writable and not a class instance - replace it
+                    target[key] = value;
                 }
             }
             else {

package/assignGingerly.ts

@@ -29,28 +29,37 @@ export interface ItemscopeManagerConfig<T = any> {
   };
 }
 
-// Polyfill for WeakMap.prototype.getOrInsert
-
-// if (typeof WeakMap.prototype.getOrInsertComputed !== 'function') {
-//   WeakMap.prototype.getOrInsertComputed = function(key, insert) {
-//     if (this.has(key)) return this.get(key);
-//     const value = insert();
-//     this.set(key, value);
-//     return value;
-//   };
-// }
-
-// /**
-//  * @deprecated Use EnhancementConfig instead
-//  */
-// export type IBaseRegistryItem<T = any> = EnhancementConfig<T>;
-
 /**
  * Interface for the options passed to assignGingerly
  */
 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>;
 }
 
 /**
@@ -356,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
  */
@@ -368,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
@@ -540,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]))) {
@@ -575,11 +702,8 @@ 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 - normal recursive merge
-          if (!(key in target) || typeof target[key] !== 'object') {
-            target[key] = {};
-          }
-          assignGingerly(target[key], value, options);
+          // Property is writable and not a class instance - replace it
+          target[key] = value;
         }
       } else {
         target[key] = value;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.24",
+  "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": {
@@ -63,9 +63,9 @@
     "chrome": "npx playwright cr http://localhost:8000"
   },
   "devDependencies": {
-    "@playwright/test": "1.59.0-alpha-2026-02-28",
+    "@playwright/test": "1.59.1",
     "spa-ssi": "0.0.27",
-    "@types/node": "25.5.0",
+    "@types/node": "25.5.2",
     "typescript": "6.0.2"
   }
 }

package/playwright.config.ts

@@ -34,15 +34,15 @@ export default defineConfig({
       use: { ...devices['Desktop Chrome'] },
     },
 
-    // {
-    //   name: 'firefox',
-    //   use: { ...devices['Desktop Firefox'] },
-    // },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
 
-    // {
-    //   name: 'webkit',
-    //   use: { ...devices['Desktop Safari'] },
-    // },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
   ],
 
   /* Run your local dev server before starting the tests */

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>;
 }
 
 /**