assign-gingerly 0.0.31 → 0.0.33

package/assignGingerly.ts

@@ -60,6 +60,43 @@ export interface IAssignGingerlyOptions {
    * // Calls: elementRef.deref().querySelector('myElement').classList.add('active')
    */
   withMethods?: string[] | Set<string>;
+  
+  /**
+   * Alias mappings for property and method names.
+   * Allows shorter, customizable shortcuts in path expressions.
+   * 
+   * Aliases are substituted before path evaluation, matching complete tokens
+   * between `?.` delimiters (not substrings).
+   * 
+   * Reserved characters (cannot be used in aliases): space, backtick (`)
+   * 
+   * Example:
+   * assignGingerly(element, {
+   *   '?.$?.my-element?.c?.+': 'highlighted'
+   * }, { 
+   *   withMethods: ['querySelector', 'add'],
+   *   aka: { '$': 'querySelector', 'c': 'classList', '+': 'add' }
+   * });
+   * // Equivalent to: element.querySelector('my-element').classList.add('highlighted')
+   */
+  aka?: Record<string, string>;
+  
+  /**
+   * AbortSignal for cleaning up reactive subscriptions (@eachTime)
+   * Required when using @eachTime symbol for reactive iteration
+   * When the signal is aborted, all event listeners are automatically removed
+   * 
+   * Example:
+   * const controller = new AbortController();
+   * assignGingerly(div, {
+   *   '?.mountObserver?.@eachTime?.classList?.add': 'highlighted'
+   * }, { 
+   *   withMethods: ['add'],
+   *   signal: controller.signal
+   * });
+   * // Later: controller.abort(); // Cleanup all listeners
+   */
+  signal?: AbortSignal;
 }
 
 /**
@@ -319,12 +356,17 @@ function ensureNestedPath(obj: any, pathParts: string[]): any {
 }
 
 /**
- * Helper function to check if a property is readonly
- * A property is readonly if:
+ * Helper function to check if a property should be merged into rather than replaced.
+ * A property is non-replaceable if:
  * - It's a data property with writable: false, OR
  * - It's an accessor property with a getter but no setter
+ * 
+ * Properties with both a getter and setter (e.g., element.style) are treated as
+ * replaceable — the setter runs with whatever value is provided (garbage in, garbage out).
+ * 
+ * Exported for use by eachTime.ts
  */
-function isReadonlyProperty(obj: any, propName: string | symbol): boolean {
+export function isReadonlyProperty(obj: any, propName: string | symbol): boolean {
   let descriptor = Object.getOwnPropertyDescriptor(obj, propName);
   
   if (!descriptor) {
@@ -344,8 +386,8 @@ function isReadonlyProperty(obj: any, propName: string | symbol): boolean {
     return descriptor.writable === false;
   }
   
-  // If it's an accessor property, check if it has only a getter (no setter)
-  if ('get' in descriptor) {
+  // If it's an accessor property with a getter but no setter, it's readonly
+  if ('get' in descriptor && descriptor.get !== undefined) {
     return descriptor.set === undefined;
   }
   
@@ -355,8 +397,10 @@ function isReadonlyProperty(obj: any, propName: string | symbol): boolean {
 /**
  * Helper function to check if a value is a class instance (not a plain object)
  * Returns true for instances of classes, false for plain objects, arrays, and primitives
+ * 
+ * Exported for use by eachTime.ts
  */
-function isClassInstance(value: any): boolean {
+export function isClassInstance(value: any): boolean {
   if (!value || typeof value !== 'object') return false;
   if (Array.isArray(value)) return false;
   
@@ -368,8 +412,10 @@ function isClassInstance(value: any): boolean {
 /**
  * Helper function to evaluate a nested path with method calls
  * Handles chained method calls where path segments can be methods
+ * 
+ * Exported for use by eachTime.ts
  */
-function evaluatePathWithMethods(
+export function evaluatePathWithMethods(
   target: any,
   pathParts: string[],
   value: any,
@@ -421,6 +467,172 @@ function evaluatePathWithMethods(
   };
 }
 
+/**
+ * Check if a value is iterable (can be used with for...of or has forEach)
+ */
+function isIterable(value: any): boolean {
+  if (value == null) return false;
+  
+  // Check for Symbol.iterator
+  if (typeof value[Symbol.iterator] === 'function') return true;
+  
+  // Check if it's an Array
+  if (Array.isArray(value)) return true;
+  
+  // Check if it's array-like (has length and numeric indices)
+  // This covers NodeList, HTMLCollection, etc.
+  if (typeof value.length === 'number' && value.length >= 0) {
+    return true;
+  }
+  
+  return false;
+}
+
+/**
+ * Check if a segment is the forEach symbol (@each) or aliased to it
+ */
+function isForEachSymbol(segment: string, aliasMap: Map<string, string>): boolean {
+  // Direct match
+  if (segment === '@each') return true;
+  
+  // Check if this segment is aliased to '@each'
+  const aliasTarget = aliasMap.get(segment);
+  return aliasTarget === '@each';
+}
+
+/**
+ * Check if a segment is the reactive forEach symbol (@eachTime) or aliased to it
+ */
+function isReactiveForEachSymbol(segment: string, aliasMap: Map<string, string>): boolean {
+  // Direct match
+  if (segment === '@eachTime') return true;
+  
+  // Check if this segment is aliased to '@eachTime'
+  const aliasTarget = aliasMap.get(segment);
+  return aliasTarget === '@eachTime';
+}
+
+/**
+ * Apply a path to each item in an iterable
+ */
+function applyToEach(
+  iterable: any,
+  remainingPath: string[],
+  value: any,
+  withMethods: Set<string>,
+  aliasMap: Map<string, string>,
+  options?: IAssignGingerlyOptions
+): void {
+  // Convert to array for iteration
+  const items = Array.isArray(iterable) ? iterable : Array.from(iterable);
+  
+  // Apply the remaining path to each item
+  for (const item of items) {
+    if (remainingPath.length === 0) {
+      // No remaining path, can't do anything
+      continue;
+    }
+    
+    // Check if there's another @each in the remaining path
+    const forEachIndex = remainingPath.findIndex(part => isForEachSymbol(part, aliasMap));
+    
+    if (forEachIndex !== -1) {
+      // There's a nested @each
+      // Evaluate path up to the @each
+      const pathToForEach = remainingPath.slice(0, forEachIndex);
+      const pathAfterForEach = remainingPath.slice(forEachIndex + 1);
+      
+      // Navigate to the nested iterable
+      let current = item;
+      for (const part of pathToForEach) {
+        if (withMethods.has(part)) {
+          const method = current[part];
+          if (typeof method === 'function') {
+            // For methods in the middle, we need to check the next part
+            const nextIndex = pathToForEach.indexOf(part) + 1;
+            const nextPart = pathToForEach[nextIndex];
+            if (nextPart && withMethods.has(nextPart)) {
+              current = method.call(current);
+            } else if (nextPart) {
+              current = method.call(current, nextPart);
+              // Skip next part
+              pathToForEach.splice(nextIndex, 1);
+            } else {
+              current = method.call(current);
+            }
+          } else {
+            current = current[part];
+          }
+        } else {
+          current = current[part];
+        }
+      }
+      
+      // Recursively apply to the nested iterable
+      if (isIterable(current)) {
+        applyToEach(current, pathAfterForEach, value, withMethods, aliasMap, options);
+      }
+    } else {
+      // No nested @each, evaluate the remaining path normally
+      const result = evaluatePathWithMethods(item, remainingPath, value, withMethods);
+      
+      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);
+          }
+        }
+      } else {
+        // Normal assignment
+        const lastKey = result.lastKey;
+        const parent = result.target;
+        
+        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+          if (lastKey in parent && isReadonlyProperty(parent, lastKey)) {
+            const currentValue = parent[lastKey];
+            if (typeof currentValue !== 'object' || currentValue === null) {
+              throw new Error(`Cannot merge object into readonly primitive property '${String(lastKey)}'`);
+            }
+            assignGingerly(currentValue, value, options);
+          } else {
+            parent[lastKey] = value;
+          }
+        } else {
+          parent[lastKey] = value;
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Apply alias substitutions to a key string.
+ * Replaces complete tokens between `?.` delimiters with their aliased values.
+ * 
+ * @param key - The key string (e.g., '?.$?.my-element?.c?.+')
+ * @param aliasMap - Map of alias -> target name
+ * @returns The key with aliases substituted (e.g., '?.querySelector?.my-element?.classList?.add')
+ */
+function applyAliases(key: string, aliasMap: Map<string, string>): string {
+  if (aliasMap.size === 0) return key;
+  
+  // Split by ?. to get tokens
+  const parts = key.split('?.');
+  
+  // Apply aliases to each part
+  const substituted = parts.map(part => {
+    // Check if this exact part is an alias
+    return aliasMap.get(part) ?? part;
+  });
+  
+  // Rejoin with ?.
+  return substituted.join('?.');
+}
+
 /**
  * Main assignGingerly function
  */
@@ -440,13 +652,25 @@ export function assignGingerly(
       : new Set(options.withMethods)
     : undefined;
 
+  // Convert aka object to Map for O(1) lookup and validate aliases
+  const aliasMap = new Map<string, string>();
+  if (options?.aka) {
+    for (const [alias, target] of Object.entries(options.aka)) {
+      // Validate: disallow space and backtick in aliases
+      if (alias.includes(' ') || alias.includes('`')) {
+        throw new Error(`Invalid alias '${alias}': aliases cannot contain space or backtick characters`);
+      }
+      aliasMap.set(alias, target);
+    }
+  }
+
   const registry = options?.registry instanceof EnhancementRegistry
     ? options.registry
     : options?.registry
     ? new options.registry()
     : undefined;
 
-  // Convert Symbol.for string keys to actual symbols
+  // Convert Symbol.for string keys to actual symbols and apply aliases
   const processedSource: Record<string | symbol, any> = {};
   for (const key of Object.keys(source)) {
     if (isSymbolForKey(key)) {
@@ -458,7 +682,9 @@ export function assignGingerly(
         processedSource[key] = source[key];
       }
     } else {
-      processedSource[key] = source[key];
+      // Apply aliases to string keys
+      const substitutedKey = applyAliases(key, aliasMap);
+      processedSource[substitutedKey] = source[key];
     }
   }
   // Copy over actual symbol keys
@@ -613,6 +839,65 @@ export function assignGingerly(
     if (isNestedPath(key)) {
       const pathParts = parsePath(key);
       
+      // Check if path contains @each or @eachTime (forEach)
+      const forEachIndex = pathParts.findIndex(part => 
+        isForEachSymbol(part, aliasMap) || isReactiveForEachSymbol(part, aliasMap)
+      );
+      
+      if (forEachIndex !== -1) {
+        // Check if it's reactive (@eachTime)
+        const isReactive = isReactiveForEachSymbol(pathParts[forEachIndex], aliasMap);
+        
+        if (isReactive) {
+          // Reactive forEach - dynamic load and fire-and-forget
+          (async () => {
+            try {
+              const { handleEachTime } = await import('./eachTime.js');
+              await handleEachTime(
+                target,
+                pathParts,
+                forEachIndex,
+                value,
+                withMethodsSet,
+                aliasMap,
+                options
+              );
+            } catch (error) {
+              console.error('Error in @eachTime:', error);
+            }
+          })();
+          continue;
+        }
+        
+        // Static forEach (@each) - existing logic
+        const pathToForEach = pathParts.slice(0, forEachIndex);
+        const pathAfterForEach = pathParts.slice(forEachIndex + 1);
+        
+        // Navigate to the iterable
+        let current = target;
+        if (pathToForEach.length > 0) {
+          if (withMethodsSet) {
+            const result = evaluatePathWithMethods(target, pathToForEach, value, withMethodsSet);
+            // The result.target is the current position after evaluating the path
+            // This is already the iterable we want
+            current = result.target;
+          } else {
+            for (const part of pathToForEach) {
+              current = current[part];
+            }
+          }
+        }
+        
+        // Apply to each item in the iterable
+        if (isIterable(current)) {
+          applyToEach(current, pathAfterForEach, value, withMethodsSet || new Set(), aliasMap, options);
+        }
+        // If not iterable, let JavaScript throw error naturally when trying to iterate
+        
+        continue;
+      }
+      
+      // No @each in path - handle normally
       // Check if we need to handle methods
       if (withMethodsSet) {
         const result = evaluatePathWithMethods(target, pathParts, value, withMethodsSet);
@@ -636,15 +921,15 @@ export function assignGingerly(
         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]))) {
+          // Check if property exists and is readonly
+          if (lastKey in parent && isReadonlyProperty(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)}'`);
+              throw new Error(`Cannot merge object into readonly primitive property '${String(lastKey)}'`);
             }
             assignGingerly(currentValue, value, options);
           } else {
-            // Property is writable and not a class instance - replace it
+            // Property is writable - replace it
             parent[lastKey] = value;
           }
         } else {
@@ -656,17 +941,17 @@ export function assignGingerly(
         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
+          // Check if property exists and is readonly
+          if (lastKey in parent && isReadonlyProperty(parent, lastKey)) {
+            // Property is readonly - 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)}'`);
+              throw new Error(`Cannot merge object into readonly primitive property '${String(lastKey)}'`);
             }
-            // Recursively apply assignGingerly to the readonly object or class instance
+            // Recursively apply assignGingerly to the readonly object
             assignGingerly(currentValue, value, options);
           } else {
-            // Property is writable and not a class instance - replace it
+            // Property is writable - replace it
             parent[lastKey] = value;
           }
         } else {
@@ -692,17 +977,17 @@ export function assignGingerly(
       
       // 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]))) {
-          // Property is readonly or a class instance - check if current value is an object
+        // Check if property exists and is readonly
+        if (key in target && isReadonlyProperty(target, key)) {
+          // Property is readonly - check if current value is an object
           const currentValue = target[key];
           if (typeof currentValue !== 'object' || currentValue === null) {
-            throw new Error(`Cannot merge object into ${isReadonlyProperty(target, key) ? 'readonly ' : ''}primitive property '${String(key)}'`);
+            throw new Error(`Cannot merge object into readonly primitive property '${String(key)}'`);
           }
-          // Recursively apply assignGingerly to the readonly object or class instance
+          // Recursively apply assignGingerly to the readonly object
           assignGingerly(currentValue, value, options);
         } else {
-          // Property is writable and not a class instance - replace it
+          // Property is writable - replace it
           target[key] = value;
         }
       } else {

package/eachTime.js

@@ -0,0 +1,110 @@
+/**
+ * eachTime.ts - Reactive forEach implementation for @eachTime symbol
+ * This module is dynamically loaded only when @eachTime is encountered
+ * Provides event-driven iteration over elements as they mount
+ */
+/**
+ * Check if a value is an EventTarget
+ */
+function isEventTarget(value) {
+    return value != null && typeof value.addEventListener === 'function';
+}
+/**
+ * Handle reactive forEach (@eachTime) by setting up event listeners
+ *
+ * @param target - The root object to start navigation from
+ * @param pathParts - Complete path parts array including @eachTime
+ * @param forEachIndex - Index of @eachTime in pathParts
+ * @param value - Value to assign to each mounted element
+ * @param withMethods - Set of method names to call instead of assign
+ * @param aliasMap - Map of aliases for token substitution
+ * @param options - Options including required AbortSignal
+ */
+export async function handleEachTime(target, pathParts, forEachIndex, value, withMethods, aliasMap, options) {
+    // Validate signal - required for cleanup
+    if (!options?.signal) {
+        throw new Error('@eachTime requires an AbortSignal in options.signal for cleanup');
+    }
+    // Split path into before and after @eachTime
+    const pathToEventSource = pathParts.slice(0, forEachIndex);
+    const pathAfterForEach = pathParts.slice(forEachIndex + 1);
+    // Navigate to the event source
+    let eventSource = target;
+    if (pathToEventSource.length > 0) {
+        // Import evaluatePathWithMethods for navigation
+        const { evaluatePathWithMethods } = await import('./assignGingerly.js');
+        if (withMethods && withMethods.size > 0) {
+            const result = evaluatePathWithMethods(target, pathToEventSource, value, withMethods);
+            eventSource = result.target;
+        }
+        else {
+            // Simple property navigation
+            for (const part of pathToEventSource) {
+                eventSource = eventSource[part];
+            }
+        }
+    }
+    // Validate event source is an EventTarget
+    if (!isEventTarget(eventSource)) {
+        throw new Error('@eachTime requires an EventTarget (e.g., IMountObserver)');
+    }
+    // Setup event listener for 'mount' events
+    const handler = (event) => {
+        // Extract mounted element from IMountEvent
+        const mountedElement = event.mountedElement;
+        if (!mountedElement)
+            return;
+        // Apply remaining path to mounted element (async to avoid blocking)
+        (async () => {
+            try {
+                // Import needed functions from assignGingerly
+                const { evaluatePathWithMethods, assignGingerly, isReadonlyProperty } = await import('./assignGingerly.js');
+                if (pathAfterForEach.length > 0) {
+                    const result = evaluatePathWithMethods(mountedElement, pathAfterForEach, value, withMethods || new Set());
+                    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);
+                            }
+                        }
+                    }
+                    else {
+                        // Normal assignment
+                        const lastKey = result.lastKey;
+                        const parent = result.target;
+                        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                            // Check if property exists and is readonly
+                            if (lastKey in parent && isReadonlyProperty(parent, lastKey)) {
+                                const currentValue = parent[lastKey];
+                                if (typeof currentValue !== 'object' || currentValue === null) {
+                                    throw new Error(`Cannot merge object into readonly primitive property '${String(lastKey)}'`);
+                                }
+                                // Recursively apply assignGingerly
+                                assignGingerly(currentValue, value, options);
+                            }
+                            else {
+                                // Property is writable - replace it
+                                parent[lastKey] = value;
+                            }
+                        }
+                        else {
+                            // Primitive value - direct assignment
+                            parent[lastKey] = value;
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                console.error('Error applying @eachTime to mounted element:', error);
+            }
+        })();
+    };
+    // Register listener with AbortSignal for automatic cleanup
+    // Hardcode 'mount' event for IMountObserver
+    eventSource.addEventListener('mount', handler, { signal: options.signal });
+}

package/eachTime.ts

@@ -0,0 +1,136 @@
+/**
+ * eachTime.ts - Reactive forEach implementation for @eachTime symbol
+ * This module is dynamically loaded only when @eachTime is encountered
+ * Provides event-driven iteration over elements as they mount
+ */
+
+import type { IAssignGingerlyOptions } from './assignGingerly.js';
+
+/**
+ * Check if a value is an EventTarget
+ */
+function isEventTarget(value: any): boolean {
+  return value != null && typeof value.addEventListener === 'function';
+}
+
+/**
+ * Handle reactive forEach (@eachTime) by setting up event listeners
+ * 
+ * @param target - The root object to start navigation from
+ * @param pathParts - Complete path parts array including @eachTime
+ * @param forEachIndex - Index of @eachTime in pathParts
+ * @param value - Value to assign to each mounted element
+ * @param withMethods - Set of method names to call instead of assign
+ * @param aliasMap - Map of aliases for token substitution
+ * @param options - Options including required AbortSignal
+ */
+export async function handleEachTime(
+  target: any,
+  pathParts: string[],
+  forEachIndex: number,
+  value: any,
+  withMethods: Set<string> | undefined,
+  aliasMap: Map<string, string>,
+  options?: IAssignGingerlyOptions
+): Promise<void> {
+  // Validate signal - required for cleanup
+  if (!options?.signal) {
+    throw new Error('@eachTime requires an AbortSignal in options.signal for cleanup');
+  }
+  
+  // Split path into before and after @eachTime
+  const pathToEventSource = pathParts.slice(0, forEachIndex);
+  const pathAfterForEach = pathParts.slice(forEachIndex + 1);
+  
+  // Navigate to the event source
+  let eventSource = target;
+  if (pathToEventSource.length > 0) {
+    // Import evaluatePathWithMethods for navigation
+    const { evaluatePathWithMethods } = await import('./assignGingerly.js');
+    
+    if (withMethods && withMethods.size > 0) {
+      const result = evaluatePathWithMethods(target, pathToEventSource, value, withMethods);
+      eventSource = result.target;
+    } else {
+      // Simple property navigation
+      for (const part of pathToEventSource) {
+        eventSource = eventSource[part];
+      }
+    }
+  }
+  
+  // Validate event source is an EventTarget
+  if (!isEventTarget(eventSource)) {
+    throw new Error('@eachTime requires an EventTarget (e.g., IMountObserver)');
+  }
+  
+  // Setup event listener for 'mount' events
+  const handler = (event: Event) => {
+    // Extract mounted element from IMountEvent
+    const mountedElement = (event as any).mountedElement;
+    if (!mountedElement) return;
+    
+    // Apply remaining path to mounted element (async to avoid blocking)
+    (async () => {
+      try {
+        // Import needed functions from assignGingerly
+        const { 
+          evaluatePathWithMethods, 
+          assignGingerly, 
+          isReadonlyProperty
+        } = await import('./assignGingerly.js');
+        
+        if (pathAfterForEach.length > 0) {
+          const result = evaluatePathWithMethods(
+            mountedElement, 
+            pathAfterForEach, 
+            value, 
+            withMethods || new Set()
+          );
+          
+          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);
+              }
+            }
+          } else {
+            // Normal assignment
+            const lastKey = result.lastKey;
+            const parent = result.target;
+            
+            if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+              // Check if property exists and is readonly
+              if (lastKey in parent && isReadonlyProperty(parent, lastKey)) {
+                const currentValue = parent[lastKey];
+                if (typeof currentValue !== 'object' || currentValue === null) {
+                  throw new Error(
+                    `Cannot merge object into readonly primitive property '${String(lastKey)}'`
+                  );
+                }
+                // Recursively apply assignGingerly
+                assignGingerly(currentValue, value, options);
+              } else {
+                // Property is writable - replace it
+                parent[lastKey] = value;
+              }
+            } else {
+              // Primitive value - direct assignment
+              parent[lastKey] = value;
+            }
+          }
+        }
+      } catch (error) {
+        console.error('Error applying @eachTime to mounted element:', error);
+      }
+    })();
+  };
+  
+  // Register listener with AbortSignal for automatic cleanup
+  // Hardcode 'mount' event for IMountObserver
+  eventSource.addEventListener('mount', handler, { signal: options.signal });
+}