assign-gingerly 0.0.30 → 0.0.32

package/assignFrom.js

@@ -0,0 +1,27 @@
+/**
+ * Resolve RHS path strings against a source object, then assign the
+ * resolved values into a target using assignGingerly.
+ *
+ * Combines resolveValues + assignGingerly into a single call.
+ * Inherits all assignGingerly options (withMethods, aka, signal, etc.).
+ *
+ * @param target - Object to merge resolved values into
+ * @param pattern - Object whose RHS values may contain `?.` path strings
+ * @param options - Options including `from` (source object) and any assignGingerly options
+ * @returns The target object after merging
+ *
+ * @example
+ * const source = { theme: { color: 'red' }, label: 'Hello' };
+ * const target = { color: 'blue', text: '' };
+ * assignFrom(target, {
+ *   color: '?.theme?.color',
+ *   text: '?.label'
+ * }, { from: source });
+ * // target is now { color: 'red', text: 'Hello' }
+ */
+import { resolveValues } from './resolveValues.js';
+import assignGingerly from './assignGingerly.js';
+export function assignFrom(target, pattern, options) {
+    const resolved = resolveValues(pattern, options.from);
+    return assignGingerly(target, resolved, options);
+}

package/assignFrom.ts

@@ -0,0 +1,37 @@
+/**
+ * Resolve RHS path strings against a source object, then assign the
+ * resolved values into a target using assignGingerly.
+ * 
+ * Combines resolveValues + assignGingerly into a single call.
+ * Inherits all assignGingerly options (withMethods, aka, signal, etc.).
+ * 
+ * @param target - Object to merge resolved values into
+ * @param pattern - Object whose RHS values may contain `?.` path strings
+ * @param options - Options including `from` (source object) and any assignGingerly options
+ * @returns The target object after merging
+ * 
+ * @example
+ * const source = { theme: { color: 'red' }, label: 'Hello' };
+ * const target = { color: 'blue', text: '' };
+ * assignFrom(target, {
+ *   color: '?.theme?.color',
+ *   text: '?.label'
+ * }, { from: source });
+ * // target is now { color: 'red', text: 'Hello' }
+ */
+import { resolveValues } from './resolveValues.js';
+import assignGingerly, { IAssignGingerlyOptions } from './assignGingerly.js';
+
+export interface AssignFromOptions extends IAssignGingerlyOptions {
+  /** Source object to resolve RHS path strings against */
+  from: any;
+}
+
+export function assignFrom(
+  target: any,
+  pattern: Record<string, any>,
+  options: AssignFromOptions
+): any {
+  const resolved = resolveValues(pattern, options.from);
+  return assignGingerly(target, resolved, options);
+}

package/assignGingerly.js

@@ -232,8 +232,10 @@ function ensureNestedPath(obj, pathParts) {
  * A property is readonly if:
  * - It's a data property with writable: false, OR
  * - It's an accessor property with a getter but no setter
+ *
+ * Exported for use by eachTime.ts
  */
-function isReadonlyProperty(obj, propName) {
+export function isReadonlyProperty(obj, propName) {
     let descriptor = Object.getOwnPropertyDescriptor(obj, propName);
     if (!descriptor) {
         // Check prototype chain
@@ -260,8 +262,10 @@ function isReadonlyProperty(obj, propName) {
 /**
  * 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) {
+export function isClassInstance(value) {
     if (!value || typeof value !== 'object')
         return false;
     if (Array.isArray(value))
@@ -273,8 +277,10 @@ function isClassInstance(value) {
 /**
  * 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(target, pathParts, value, withMethods) {
+export function evaluatePathWithMethods(target, pathParts, value, withMethods) {
     let current = target;
     let i = 0;
     // Process all segments except the last one
@@ -319,6 +325,159 @@ function evaluatePathWithMethods(target, pathParts, value, withMethods) {
         isMethod: withMethods.has(lastKey)
     };
 }
+/**
+ * Check if a value is iterable (can be used with for...of or has forEach)
+ */
+function isIterable(value) {
+    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, aliasMap) {
+    // 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, aliasMap) {
+    // 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, remainingPath, value, withMethods, aliasMap, options) {
+    // 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) || 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 {
+                        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, aliasMap) {
+    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
  */
@@ -332,12 +491,23 @@ export function assignGingerly(target, source, options) {
             ? options.withMethods
             : new Set(options.withMethods)
         : undefined;
+    // Convert aka object to Map for O(1) lookup and validate aliases
+    const aliasMap = new Map();
+    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 = {};
     for (const key of Object.keys(source)) {
         if (isSymbolForKey(key)) {
@@ -351,7 +521,9 @@ export function assignGingerly(target, source, options) {
             }
         }
         else {
-            processedSource[key] = source[key];
+            // Apply aliases to string keys
+            const substitutedKey = applyAliases(key, aliasMap);
+            processedSource[substitutedKey] = source[key];
         }
     }
     // Copy over actual symbol keys
@@ -492,6 +664,50 @@ export function assignGingerly(target, source, options) {
         }
         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);

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;
 }
 
 /**
@@ -323,8 +360,10 @@ function ensureNestedPath(obj: any, pathParts: string[]): any {
  * A property is readonly if:
  * - It's a data property with writable: false, OR
  * - It's an accessor property with a getter but no setter
+ * 
+ * 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) {
@@ -355,8 +394,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 +409,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 +464,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) || 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 {
+            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 +649,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 +679,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 +836,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);