assign-gingerly 0.0.25 → 0.0.27

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/ScopedParserRegistry.js

@@ -0,0 +1,94 @@
+/**
+ * Registry for parsers scoped to a synthesizer element (be-hive, htmx-container, etc.)
+ * Enables lazy-loading of complex parsers with Promise-based waiting
+ */
+export class ScopedParserRegistry {
+    parsers = new Map();
+    pendingWaits = new Map();
+    /**
+     * Register a parser with a given name
+     * Resolves any pending waiters for this parser
+     * @param name - The name to register the parser under
+     * @param parser - The parser function
+     */
+    register(name, parser) {
+        if (this.parsers.has(name)) {
+            console.warn(`Parser "${name}" already registered in scoped registry, overwriting`);
+        }
+        this.parsers.set(name, parser);
+        // Resolve any pending waiters for this parser
+        const waiters = this.pendingWaits.get(name);
+        if (waiters) {
+            waiters.forEach(({ resolve }) => resolve());
+            this.pendingWaits.delete(name);
+        }
+    }
+    /**
+     * Get a parser by name
+     * @param name - The name of the parser
+     * @returns The parser function or undefined if not found
+     */
+    get(name) {
+        return this.parsers.get(name);
+    }
+    /**
+     * Check if a parser is registered
+     * @param name - The name to check
+     * @returns True if the parser exists
+     */
+    has(name) {
+        return this.parsers.has(name);
+    }
+    /**
+     * Wait for multiple parsers to be registered
+     * @param names - Array of parser names to wait for
+     * @param timeout - Timeout in milliseconds (default: 60000)
+     * @returns Promise that resolves when all parsers are registered
+     * @throws Error listing missing parsers if timeout expires
+     */
+    waitFor(names, timeout = 60000) {
+        // Check if all parsers are already registered
+        const missing = names.filter(name => !this.has(name));
+        if (missing.length === 0) {
+            return Promise.resolve();
+        }
+        // Create promise that resolves when all parsers are registered
+        return new Promise((resolve, reject) => {
+            let timeoutId;
+            // Set timeout that rejects with descriptive error
+            timeoutId = setTimeout(() => {
+                const stillMissing = names.filter(name => !this.has(name));
+                reject(new Error(`Timeout waiting for parsers: ${stillMissing.join(', ')}`));
+            }, timeout);
+            // Track which parsers we're waiting for
+            let remainingCount = missing.length;
+            // Create waiter for each missing parser
+            missing.forEach(name => {
+                const waiter = {
+                    resolve: () => {
+                        remainingCount--;
+                        if (remainingCount === 0) {
+                            if (timeoutId !== undefined) {
+                                clearTimeout(timeoutId);
+                            }
+                            resolve();
+                        }
+                    },
+                    reject
+                };
+                // Add waiter to pending list
+                if (!this.pendingWaits.has(name)) {
+                    this.pendingWaits.set(name, []);
+                }
+                this.pendingWaits.get(name).push(waiter);
+            });
+        });
+    }
+    /**
+     * Get all registered parser names
+     * @returns Array of parser names
+     */
+    getNames() {
+        return Array.from(this.parsers.keys());
+    }
+}

package/ScopedParserRegistry.ts

@@ -0,0 +1,111 @@
+import { ParserFunction } from './types/assign-gingerly/types';
+
+/**
+ * Registry for parsers scoped to a synthesizer element (be-hive, htmx-container, etc.)
+ * Enables lazy-loading of complex parsers with Promise-based waiting
+ */
+export class ScopedParserRegistry {
+  private parsers = new Map<string, ParserFunction>();
+  private pendingWaits = new Map<string, Array<{
+    resolve: () => void;
+    reject: (error: Error) => void;
+  }>>();
+  
+  /**
+   * Register a parser with a given name
+   * Resolves any pending waiters for this parser
+   * @param name - The name to register the parser under
+   * @param parser - The parser function
+   */
+  register(name: string, parser: ParserFunction): void {
+    if (this.parsers.has(name)) {
+      console.warn(`Parser "${name}" already registered in scoped registry, overwriting`);
+    }
+    
+    this.parsers.set(name, parser);
+    
+    // Resolve any pending waiters for this parser
+    const waiters = this.pendingWaits.get(name);
+    if (waiters) {
+      waiters.forEach(({ resolve }) => resolve());
+      this.pendingWaits.delete(name);
+    }
+  }
+  
+  /**
+   * Get a parser by name
+   * @param name - The name of the parser
+   * @returns The parser function or undefined if not found
+   */
+  get(name: string): ParserFunction | undefined {
+    return this.parsers.get(name);
+  }
+  
+  /**
+   * Check if a parser is registered
+   * @param name - The name to check
+   * @returns True if the parser exists
+   */
+  has(name: string): boolean {
+    return this.parsers.has(name);
+  }
+  
+  /**
+   * Wait for multiple parsers to be registered
+   * @param names - Array of parser names to wait for
+   * @param timeout - Timeout in milliseconds (default: 60000)
+   * @returns Promise that resolves when all parsers are registered
+   * @throws Error listing missing parsers if timeout expires
+   */
+  waitFor(names: string[], timeout: number = 60000): Promise<void> {
+    // Check if all parsers are already registered
+    const missing = names.filter(name => !this.has(name));
+    if (missing.length === 0) {
+      return Promise.resolve();
+    }
+    
+    // Create promise that resolves when all parsers are registered
+    return new Promise((resolve, reject) => {
+      let timeoutId: ReturnType<typeof setTimeout> | undefined;
+      
+      // Set timeout that rejects with descriptive error
+      timeoutId = setTimeout(() => {
+        const stillMissing = names.filter(name => !this.has(name));
+        reject(new Error(`Timeout waiting for parsers: ${stillMissing.join(', ')}`));
+      }, timeout);
+      
+      // Track which parsers we're waiting for
+      let remainingCount = missing.length;
+      
+      // Create waiter for each missing parser
+      missing.forEach(name => {
+        const waiter = {
+          resolve: () => {
+            remainingCount--;
+            if (remainingCount === 0) {
+              if (timeoutId !== undefined) {
+                clearTimeout(timeoutId);
+              }
+              resolve();
+            }
+          },
+          reject
+        };
+        
+        // Add waiter to pending list
+        if (!this.pendingWaits.has(name)) {
+          this.pendingWaits.set(name, []);
+        }
+        this.pendingWaits.get(name)!.push(waiter);
+      });
+    });
+  }
+  
+  /**
+   * Get all registered parser names
+   * @returns Array of parser names
+   */
+  getNames(): string[] {
+    return Array.from(this.parsers.keys());
+  }
+}

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