assign-gingerly 0.0.31 → 0.0.33

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

@@ -228,12 +228,17 @@ function ensureNestedPath(obj, pathParts) {
     return current;
 }
 /**
- * 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, propName) {
+export function isReadonlyProperty(obj, propName) {
     let descriptor = Object.getOwnPropertyDescriptor(obj, propName);
     if (!descriptor) {
         // Check prototype chain
@@ -251,8 +256,8 @@ function isReadonlyProperty(obj, propName) {
     if ('value' in descriptor) {
         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;
     }
     return false;
@@ -260,8 +265,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 +280,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 +328,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)) {
+                        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, 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 +494,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 +524,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 +667,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);
@@ -513,16 +732,16 @@ export function assignGingerly(target, source, options) {
                 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]))) {
+                    // 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;
                     }
                 }
@@ -535,18 +754,18 @@ export function assignGingerly(target, source, options) {
                 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
+                    // 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;
                     }
                 }
@@ -573,18 +792,18 @@ export function assignGingerly(target, source, options) {
             }
             // 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;
                 }
             }