assign-gingerly 0.0.79 → 0.0.80

package/DX/paths.js

@@ -27,6 +27,9 @@
  * The sp tag function uses this to auto-extract path strings from proxies.
  */
 const PATH_SYMBOL = Symbol('assign-gingerly-path');
+function isPathProxy(value) {
+    return !!value && (typeof value === 'object' || typeof value === 'function') && PATH_SYMBOL in value;
+}
 /**
  * Create a proxy for id-ref paths (#[varName]).
  * After the initial #[varName], further property access chains with ?. from the resolved element.
@@ -34,6 +37,7 @@ const PATH_SYMBOL = Symbol('assign-gingerly-path');
  */
 function createIdRefProxy(idRef, options) {
     function handler() { }
+    Object.defineProperty(handler, PATH_SYMBOL, { value: idRef });
     return new Proxy(handler, {
         get(_, prop) {
             if (prop === 'path' || prop === PATH_SYMBOL) {
@@ -53,7 +57,7 @@ function createIdRefProxy(idRef, options) {
                     argStr = 'true';
                 else if (arg === false)
                     argStr = 'false';
-                else if (arg && typeof arg === 'object' && PATH_SYMBOL in arg) {
+                else if (isPathProxy(arg)) {
                     const fullPath = arg[PATH_SYMBOL];
                     argStr = fullPath.startsWith('?.') ? fullPath.substring(2) : fullPath;
                 }
@@ -77,6 +81,7 @@ function createPathProxy(prefix, options) {
     const aliasMap = options?.aka;
     // Use a function as the target to enable the apply trap
     function handler() { }
+    Object.defineProperty(handler, PATH_SYMBOL, { value: prefix.length > 0 ? `?.${prefix}` : '?.' });
     return new Proxy(handler, {
         get(_, prop) {
             if (prop === 'path' || prop === PATH_SYMBOL) {
@@ -114,7 +119,7 @@ function createPathProxy(prefix, options) {
                     argStr = 'true';
                 else if (arg === false)
                     argStr = 'false';
-                else if (arg && typeof arg === 'object' && PATH_SYMBOL in arg) {
+                else if (isPathProxy(arg)) {
                     // Proxy arg — extract path without '?.' prefix
                     const fullPath = arg[PATH_SYMBOL];
                     argStr = fullPath.startsWith('?.') ? fullPath.substring(2) : fullPath;
@@ -167,12 +172,12 @@ export function paths(options) {
  * }
  */
 export function set(lhs) {
-    const lhsStr = lhs && typeof lhs === 'object' && PATH_SYMBOL in lhs
+    const lhsStr = isPathProxy(lhs)
         ? lhs[PATH_SYMBOL]
         : String(lhs);
     return {
         to(rhs) {
-            const rhsStr = rhs && typeof rhs === 'object' && PATH_SYMBOL in rhs
+            const rhsStr = isPathProxy(rhs)
                 ? rhs[PATH_SYMBOL]
                 : rhs;
             return { [lhsStr]: rhsStr };
@@ -198,7 +203,7 @@ export function set(lhs) {
  * // { assign: { incrementButton: '?.clone?.q?..increment', ... } }
  */
 export function smoothOver(value) {
-    if (value && typeof value === 'object' && PATH_SYMBOL in value) {
+    if (isPathProxy(value)) {
         return value[PATH_SYMBOL];
     }
     if (Array.isArray(value)) {
@@ -294,13 +299,13 @@ export function sp(strings, ...values) {
             result.push(strings[i]);
         if (i < values.length) {
             const v = values[i];
-            if (v && typeof v === 'object' && PATH_SYMBOL in v) {
+            if (isPathProxy(v)) {
                 // Auto-extract path from proxy object
                 result.push(v[PATH_SYMBOL]);
             }
             else if (Array.isArray(v)) {
                 // Nested array — recursively extract paths from proxy elements
-                result.push(v.map(el => el && typeof el === 'object' && PATH_SYMBOL in el ? el[PATH_SYMBOL] : el));
+                result.push(v.map(el => isPathProxy(el) ? el[PATH_SYMBOL] : el));
             }
             else {
                 result.push(v);
@@ -349,7 +354,7 @@ export function md(strings, ...values) {
             result.push(strings[i]);
         if (i < values.length) {
             const v = values[i];
-            if (v && typeof v === 'object' && PATH_SYMBOL in v) {
+            if (isPathProxy(v)) {
                 // Proxy object → {prop, val}
                 const pathStr = v[PATH_SYMBOL];
                 result.push({ prop: extractPropName(pathStr), val: pathStr });
@@ -357,7 +362,7 @@ export function md(strings, ...values) {
             else if (Array.isArray(v)) {
                 // Nested array — recursively convert proxy elements to {prop, val}
                 result.push(v.map(el => {
-                    if (el && typeof el === 'object' && PATH_SYMBOL in el) {
+                    if (isPathProxy(el)) {
                         const pathStr = el[PATH_SYMBOL];
                         return { prop: extractPropName(pathStr), val: pathStr };
                     }
@@ -367,7 +372,7 @@ export function md(strings, ...values) {
             else if (v && typeof v === 'object' && 'prop' in v) {
                 // Developer override object — extract val from proxy if present
                 const processed = { ...v };
-                if (processed.val && typeof processed.val === 'object' && PATH_SYMBOL in processed.val) {
+                if (isPathProxy(processed.val)) {
                     processed.val = processed.val[PATH_SYMBOL];
                 }
                 result.push(processed);

package/DX/paths.ts

@@ -27,7 +27,11 @@
  * Symbol used internally to detect path proxy objects.
  * The sp tag function uses this to auto-extract path strings from proxies.
  */
-const PATH_SYMBOL = Symbol('assign-gingerly-path');
+const PATH_SYMBOL = Symbol('assign-gingerly-path');
+
+function isPathProxy(value: unknown): value is { [PATH_SYMBOL]: string } {
+    return !!value && (typeof value === 'object' || typeof value === 'function') && PATH_SYMBOL in value;
+}
 
 /**
  * Type that maps an object type to a proxy where every property access
@@ -58,13 +62,14 @@ export interface PathsOptions {
  * After the initial #[varName], further property access chains with ?. from the resolved element.
  * .path returns the #[varName] prefix (optionally with further ?. path).
  */
-function createIdRefProxy(idRef: string, options?: PathsOptions): any {
-    function handler() {}
-    return new Proxy(handler, {
-        get(_, prop: string | symbol) {
-            if (prop === 'path' || prop === PATH_SYMBOL) {
-                return idRef;
-            }
+function createIdRefProxy(idRef: string, options?: PathsOptions): any {
+    function handler() {}
+    Object.defineProperty(handler, PATH_SYMBOL, { value: idRef });
+    return new Proxy(handler, {
+        get(_, prop: string | symbol) {
+            if (prop === 'path' || prop === PATH_SYMBOL) {
+                return idRef;
+            }
             if (typeof prop === 'symbol') return undefined;
 
             // Chain further path segments after the id ref
@@ -73,15 +78,15 @@ function createIdRefProxy(idRef: string, options?: PathsOptions): any {
         },
         apply(_, __, args) {
             if (args.length > 0) {
-                const arg = args[0];
-                let argStr: string;
-                if (arg === true) argStr = 'true';
-                else if (arg === false) argStr = 'false';
-                else if (arg && typeof arg === 'object' && PATH_SYMBOL in arg) {
-                    const fullPath = arg[PATH_SYMBOL] as string;
-                    argStr = fullPath.startsWith('?.') ? fullPath.substring(2) : fullPath;
-                }
-                else argStr = String(arg);
+                const arg = args[0];
+                let argStr: string;
+                if (arg === true) argStr = 'true';
+                else if (arg === false) argStr = 'false';
+                else if (isPathProxy(arg)) {
+                    const fullPath = arg[PATH_SYMBOL] as string;
+                    argStr = fullPath.startsWith('?.') ? fullPath.substring(2) : fullPath;
+                }
+                else argStr = String(arg);
 
                 const chained = `${idRef}?.${argStr}`;
                 return createIdRefProxy(chained, options);
@@ -98,16 +103,17 @@ function createIdRefProxy(idRef: string, options?: PathsOptions): any {
  * When `aka` is provided, property names that match an alias *value* are output
  * using the alias *key* instead (reverse alias).
  */
-function createPathProxy(prefix: string, options?: PathsOptions): any {
-    const aliasMap = options?.aka;
-
-    // Use a function as the target to enable the apply trap
-    function handler() {}
-
-    return new Proxy(handler, {
-        get(_, prop: string | symbol) {
-            if (prop === 'path' || prop === PATH_SYMBOL) {
-                return prefix.length > 0 ? `?.${prefix}` : '?.';
+function createPathProxy(prefix: string, options?: PathsOptions): any {
+    const aliasMap = options?.aka;
+
+    // Use a function as the target to enable the apply trap
+    function handler() {}
+    Object.defineProperty(handler, PATH_SYMBOL, { value: prefix.length > 0 ? `?.${prefix}` : '?.' });
+
+    return new Proxy(handler, {
+        get(_, prop: string | symbol) {
+            if (prop === 'path' || prop === PATH_SYMBOL) {
+                return prefix.length > 0 ? `?.${prefix}` : '?.';
             }
             // Ignore symbol access (Symbol.iterator, Symbol.toPrimitive, etc.)
             if (typeof prop === 'symbol') return undefined;
@@ -135,16 +141,16 @@ function createPathProxy(prefix: string, options?: PathsOptions): any {
         apply(_, __, args) {
             // Method call syntax: $.querySelector('.username') → extends path with the argument
             if (args.length > 0) {
-                const arg = args[0];
-                let argStr: string;
-                if (arg === true) argStr = 'true';
-                else if (arg === false) argStr = 'false';
-                else if (arg && typeof arg === 'object' && PATH_SYMBOL in arg) {
-                    // Proxy arg — extract path without '?.' prefix
-                    const fullPath = arg[PATH_SYMBOL] as string;
-                    argStr = fullPath.startsWith('?.') ? fullPath.substring(2) : fullPath;
-                }
-                else argStr = String(arg);
+                const arg = args[0];
+                let argStr: string;
+                if (arg === true) argStr = 'true';
+                else if (arg === false) argStr = 'false';
+                else if (isPathProxy(arg)) {
+                    // Proxy arg — extract path without '?.' prefix
+                    const fullPath = arg[PATH_SYMBOL] as string;
+                    argStr = fullPath.startsWith('?.') ? fullPath.substring(2) : fullPath;
+                }
+                else argStr = String(arg);
 
                 const newPath = prefix ? `${prefix}?.${argStr}` : argStr;
                 return createPathProxy(newPath, options);
@@ -193,18 +199,18 @@ export function paths<T>(options?: PathsOptions): PathProxy<T> {
  *     count: 1
  * }
  */
-export function set(lhs: any): { to: (rhs: any) => Record<string, any> } {
-    const lhsStr = lhs && typeof lhs === 'object' && PATH_SYMBOL in lhs
-        ? lhs[PATH_SYMBOL]
-        : String(lhs);
-    return {
-        to(rhs: any): Record<string, any> {
-            const rhsStr = rhs && typeof rhs === 'object' && PATH_SYMBOL in rhs
-                ? rhs[PATH_SYMBOL]
-                : rhs;
-            return { [lhsStr]: rhsStr };
-        }
-    };
+export function set(lhs: any): { to: (rhs: any) => Record<string, any> } {
+    const lhsStr = isPathProxy(lhs)
+        ? lhs[PATH_SYMBOL]
+        : String(lhs);
+    return {
+        to(rhs: any): Record<string, any> {
+            const rhsStr = isPathProxy(rhs)
+                ? rhs[PATH_SYMBOL]
+                : rhs;
+            return { [lhsStr]: rhsStr };
+        }
+    };
 }
 
 /**
@@ -225,19 +231,19 @@ export function set(lhs: any): { to: (rhs: any) => Record<string, any> } {
  * });
  * // { assign: { incrementButton: '?.clone?.q?..increment', ... } }
  */
-export function smoothOver(value: any): any {
-    if (value && typeof value === 'object' && PATH_SYMBOL in value) {
-        return value[PATH_SYMBOL];
-    }
+export function smoothOver(value: any): any {
+    if (isPathProxy(value)) {
+        return value[PATH_SYMBOL];
+    }
     if (Array.isArray(value)) {
         return value.map(smoothOver);
     }
     if (value && typeof value === 'object') {
         const proto = Object.getPrototypeOf(value);
         if (proto === Object.prototype || proto === null) {
-            const result: Record<string, any> = {};
-            for (const [k, v] of Object.entries(value)) {
-                result[k] = smoothOver(v);
+            const result: Record<string, any> = {};
+            for (const [k, v] of Object.entries(value)) {
+                result[k] = smoothOver(v);
             }
             return result;
         }
@@ -322,23 +328,23 @@ export function forEachKeyIn<T>(
  * sp`${$.lastName}${[', ', $.middleName]}, ${$.firstName}`
  * // ['?.lastName', [', ', '?.middleName'], ', ', '?.firstName']
  */
-export function sp(strings: TemplateStringsArray, ...values: any[]): any[] {
+export function sp(strings: TemplateStringsArray, ...values: any[]): any[] {
     const result: any[] = [];
     for (let i = 0; i < strings.length; i++) {
         if (strings[i]) result.push(strings[i]);
         if (i < values.length) {
-            const v = values[i];
-            if (v && typeof v === 'object' && PATH_SYMBOL in v) {
-                // Auto-extract path from proxy object
-                result.push(v[PATH_SYMBOL]);
-            } else if (Array.isArray(v)) {
-                // Nested array — recursively extract paths from proxy elements
-                result.push(v.map(el =>
-                    el && typeof el === 'object' && PATH_SYMBOL in el ? el[PATH_SYMBOL] : el
-                ));
-            } else {
-                result.push(v);
-            }
+            const v = values[i];
+            if (isPathProxy(v)) {
+                // Auto-extract path from proxy object
+                result.push(v[PATH_SYMBOL]);
+            } else if (Array.isArray(v)) {
+                // Nested array — recursively extract paths from proxy elements
+                result.push(v.map(el =>
+                    isPathProxy(el) ? el[PATH_SYMBOL] : el
+                ));
+            } else {
+                result.push(v);
+            }
         }
     }
     return result;
@@ -383,27 +389,27 @@ export function md(strings: TemplateStringsArray, ...values: any[]): any[] {
     for (let i = 0; i < strings.length; i++) {
         if (strings[i]) result.push(strings[i]);
         if (i < values.length) {
-            const v = values[i];
-            if (v && typeof v === 'object' && PATH_SYMBOL in v) {
-                // Proxy object → {prop, val}
-                const pathStr = v[PATH_SYMBOL] as string;
-                result.push({ prop: extractPropName(pathStr), val: pathStr });
-            } else if (Array.isArray(v)) {
-                // Nested array — recursively convert proxy elements to {prop, val}
-                result.push(v.map(el => {
-                    if (el && typeof el === 'object' && PATH_SYMBOL in el) {
-                        const pathStr = el[PATH_SYMBOL] as string;
-                        return { prop: extractPropName(pathStr), val: pathStr };
-                    }
-                    return el;
-                }));
-            } else if (v && typeof v === 'object' && 'prop' in v) {
-                // Developer override object — extract val from proxy if present
-                const processed = { ...v };
-                if (processed.val && typeof processed.val === 'object' && PATH_SYMBOL in processed.val) {
-                    processed.val = processed.val[PATH_SYMBOL];
-                }
-                result.push(processed);
+            const v = values[i];
+            if (isPathProxy(v)) {
+                // Proxy object → {prop, val}
+                const pathStr = v[PATH_SYMBOL] as string;
+                result.push({ prop: extractPropName(pathStr), val: pathStr });
+            } else if (Array.isArray(v)) {
+                // Nested array — recursively convert proxy elements to {prop, val}
+                result.push(v.map(el => {
+                    if (isPathProxy(el)) {
+                        const pathStr = el[PATH_SYMBOL] as string;
+                        return { prop: extractPropName(pathStr), val: pathStr };
+                    }
+                    return el;
+                }));
+            } else if (v && typeof v === 'object' && 'prop' in v) {
+                // Developer override object — extract val from proxy if present
+                const processed = { ...v };
+                if (isPathProxy(processed.val)) {
+                    processed.val = processed.val[PATH_SYMBOL];
+                }
+                result.push(processed);
             } else {
                 result.push(v);
             }

package/assignGingerly.js

@@ -420,6 +420,7 @@ export function isAllowedMethod(methodName, withMethods, permissionProcessor) {
 export function evaluatePathWithMethods(target, pathParts, value, withMethods, permissionProcessor) {
     let current = target;
     let i = 0;
+    let lastSegmentConsumed = false;
     // Process all segments except the last one
     while (i < pathParts.length - 1) {
         const part = pathParts[i];
@@ -442,6 +443,9 @@ export function evaluatePathWithMethods(target, pathParts, value, withMethods, p
                     // Only current is method - call with next part as string arg
                     current = method.call(current, nextPart, ...appendArgs);
                     i++; // Skip next part since we consumed it as argument
+                    if (i === pathParts.length - 1) {
+                        lastSegmentConsumed = true;
+                    }
                 }
             }
             else {
@@ -470,7 +474,8 @@ export function evaluatePathWithMethods(target, pathParts, value, withMethods, p
         target: current,
         lastKey,
         isMethod: isAllowedMethod(lastKey, withMethods, permissionProcessor),
-        isZeroArg
+        isZeroArg,
+        lastSegmentConsumed
     };
 }
 /**
@@ -623,6 +628,95 @@ function applyToEach(iterable, remainingPath, value, withMethods, aliasMap, opti
         }
     }
 }
+/**
+ * Resolve the RHS of a toggle (=!) command to the value that should be negated.
+ * Supports:
+ * - '?.path' nested path strings resolved against target (returns the resolved value, or true if missing)
+ * - plain key strings looked up on target (returns the value, or true if missing)
+ * - resolved literal values (e.g., booleans from assignFrom) returned as-is
+ */
+function resolveValueToNegate(rhsPath, target) {
+    if (typeof rhsPath === 'string' && isNestedPath(rhsPath)) {
+        const rhsPathParts = parsePath(rhsPath);
+        let current = target;
+        let exists = true;
+        for (const part of rhsPathParts) {
+            if (current && typeof current === 'object' && part in current) {
+                current = current[part];
+            }
+            else {
+                exists = false;
+                break;
+            }
+        }
+        return exists ? current : true;
+    }
+    if (typeof rhsPath === 'string') {
+        return (rhsPath in target) ? target[rhsPath] : true;
+    }
+    // Non-string resolved value (e.g., boolean, number, null from assignFrom)
+    return rhsPath;
+}
+/**
+ * Navigate a path that leads to an iterable, returning the iterable value or undefined.
+ * Handles withMethods and the evaluatePathWithMethods semantics.
+ */
+function getIterableAtPath(target, pathParts, value, withMethods, permissionProcessor) {
+    let current = target;
+    if (pathParts.length > 0) {
+        if (withMethods && withMethods.size > 0) {
+            const result = evaluatePathWithMethods(target, pathParts, value, withMethods, permissionProcessor);
+            // evaluatePathWithMethods returns the container object + last key by default.
+            // If the last segment was consumed as a method argument, or the last segment
+            // is a zero-arg method marked with |, result.target is already the value.
+            if (result.lastSegmentConsumed) {
+                current = result.target;
+            }
+            else if (result.isMethod) {
+                const method = result.target[result.lastKey];
+                if (typeof method === 'function') {
+                    const appendArgs = permissionProcessor?.getMethodAppendArgs(result.lastKey) ?? [];
+                    current = method.call(result.target, ...appendArgs);
+                }
+                else {
+                    current = method;
+                }
+            }
+            else {
+                current = result.target[result.lastKey];
+            }
+        }
+        else {
+            for (const part of pathParts) {
+                current = current[part];
+            }
+        }
+    }
+    return isIterable(current) ? current : undefined;
+}
+/**
+ * Apply an operator command (+=, =!, -=, Y=) to each item in an iterable.
+ * Detects @each in the path, navigates to the iterable, then builds a synthetic
+ * command key for the remaining path and delegates to assignGingerly per item.
+ * Nested @each is handled recursively through assignGingerly.
+ */
+function applyCommandToEach(target, pathParts, commandSuffix, value, withMethods, aliasMap, options, permissionProcessor) {
+    const forEachIndex = pathParts.findIndex(part => isForEachSymbol(part, aliasMap));
+    if (forEachIndex === -1)
+        return;
+    const pathToForEach = pathParts.slice(0, forEachIndex);
+    const pathAfterForEach = pathParts.slice(forEachIndex + 1);
+    const iterable = getIterableAtPath(target, pathToForEach, value, withMethods, permissionProcessor);
+    if (!iterable)
+        return;
+    const items = Array.isArray(iterable) ? iterable : Array.from(iterable);
+    const syntheticKey = pathAfterForEach.length > 0
+        ? `?.${pathAfterForEach.join('?.')}${commandSuffix}`
+        : commandSuffix;
+    for (const item of items) {
+        assignGingerly(item, { [syntheticKey]: value }, options, permissionProcessor);
+    }
+}
 /**
  * Apply alias substitutions to a key string.
  * Replaces complete tokens between `?.` delimiters with their aliased values.
@@ -727,6 +821,11 @@ export function assignGingerly(target, source, options, permissionProcessor) {
             if (path) {
                 if (isNestedPath(path)) {
                     const pathParts = parsePath(path);
+                    // Check for @each in path
+                    if (pathParts.some(part => isForEachSymbol(part, aliasMap))) {
+                        applyCommandToEach(target, pathParts, ' +=', value, withMethodsSet, aliasMap, options, permissionProcessor);
+                        continue;
+                    }
                     // Check for withMethods path evaluation
                     let lhsValue;
                     let lhsParent;
@@ -795,54 +894,47 @@ export function assignGingerly(target, source, options, permissionProcessor) {
             const lhsPath = parseToggleCommand(key);
             if (lhsPath) {
                 const rhsPath = value;
-                // Resolve LHS
-                let lhsParent;
-                let lhsLastKey;
                 if (isNestedPath(lhsPath)) {
                     const lhsPathParts = parsePath(lhsPath);
-                    lhsLastKey = lhsPathParts[lhsPathParts.length - 1];
-                    lhsParent = ensureNestedPath(target, lhsPathParts);
-                }
-                else {
-                    lhsLastKey = lhsPath;
-                    lhsParent = target;
-                }
-                // Determine what to negate
-                let valueToNegate;
-                if (rhsPath === '.') {
-                    // Self-reference: negate the LHS value itself (if it exists)
-                    if (lhsLastKey in lhsParent) {
-                        valueToNegate = lhsParent[lhsLastKey];
+                    // Check for @each in the LHS path
+                    if (lhsPathParts.some(part => isForEachSymbol(part, aliasMap))) {
+                        // Resolve non-self-referencing RHS paths against the original target
+                        // before iterating, so each item negates the same root value.
+                        const resolvedValue = (rhsPath === '.' || typeof rhsPath !== 'string')
+                            ? rhsPath
+                            : resolveValueToNegate(rhsPath, target);
+                        applyCommandToEach(target, lhsPathParts, ' =!', resolvedValue, withMethodsSet, aliasMap, options, permissionProcessor);
+                        continue;
+                    }
+                    // No @each in path - standard toggle
+                    const lhsLastKey = lhsPathParts[lhsPathParts.length - 1];
+                    const lhsParent = ensureNestedPath(target, lhsPathParts);
+                    // Determine what to negate
+                    let valueToNegate;
+                    if (rhsPath === '.') {
+                        valueToNegate = (lhsLastKey in lhsParent) ? lhsParent[lhsLastKey] : undefined;
                     }
                     else {
-                        valueToNegate = undefined;
+                        valueToNegate = resolveValueToNegate(rhsPath, target);
+                    }
+                    if (!permissionProcessor?.checkRestrictedProp(lhsLastKey)) {
+                        lhsParent[lhsLastKey] = !valueToNegate;
                     }
                 }
                 else {
-                    // RHS path: navigate to get the value (don't create paths)
-                    if (isNestedPath(rhsPath)) {
-                        const rhsPathParts = parsePath(rhsPath);
-                        let current = target;
-                        let exists = true;
-                        for (const part of rhsPathParts) {
-                            if (current && typeof current === 'object' && part in current) {
-                                current = current[part];
-                            }
-                            else {
-                                exists = false;
-                                break;
-                            }
-                        }
-                        valueToNegate = exists ? current : true;
+                    // Plain key LHS
+                    const lhsLastKey = lhsPath;
+                    const lhsParent = target;
+                    let valueToNegate;
+                    if (rhsPath === '.') {
+                        valueToNegate = (lhsLastKey in lhsParent) ? lhsParent[lhsLastKey] : undefined;
                     }
                     else {
-                        // Plain key RHS
-                        valueToNegate = (rhsPath in target) ? target[rhsPath] : true;
+                        valueToNegate = resolveValueToNegate(rhsPath, target);
+                    }
+                    if (!permissionProcessor?.checkRestrictedProp(lhsLastKey)) {
+                        lhsParent[lhsLastKey] = !valueToNegate;
                     }
-                }
-                // Apply negation to LHS — check restriction first
-                if (!permissionProcessor?.checkRestrictedProp(lhsLastKey)) {
-                    lhsParent[lhsLastKey] = !valueToNegate;
                 }
             }
             continue;
@@ -856,6 +948,11 @@ export function assignGingerly(target, source, options, permissionProcessor) {
                 let canDelete = true;
                 if (isNestedPath(path)) {
                     const pathParts = parsePath(path);
+                    // Check for @each in path
+                    if (pathParts.some(part => isForEachSymbol(part, aliasMap))) {
+                        applyCommandToEach(target, pathParts, ' -=', value, withMethodsSet, aliasMap, options, permissionProcessor);
+                        continue;
+                    }
                     if (pathParts.length === 0) {
                         parent = target;
                     }
@@ -901,6 +998,11 @@ export function assignGingerly(target, source, options, permissionProcessor) {
                 if (permissionProcessor?.checkRestrictedProp(lastKey)) {
                     continue;
                 }
+                // Check for @each in path
+                if (isNestedPath(path) && pathParts.some(part => isForEachSymbol(part, aliasMap))) {
+                    applyCommandToEach(target, pathParts, ' Y=', value, withMethodsSet, aliasMap, options, permissionProcessor);
+                    continue;
+                }
                 // Navigate to the target sub-object
                 let mergeTarget;
                 if (isNestedPath(path)) {
@@ -956,22 +1058,9 @@ export function assignGingerly(target, source, options, permissionProcessor) {
                 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, permissionProcessor);
-                        // 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];
-                        }
-                    }
-                }
+                const current = getIterableAtPath(target, pathToForEach, value, withMethodsSet, permissionProcessor);
                 // Apply to each item in the iterable
-                if (isIterable(current)) {
+                if (current) {
                     applyToEach(current, pathAfterForEach, value, withMethodsSet || new Set(), aliasMap, options, permissionProcessor);
                 }
                 // If not iterable, let JavaScript throw error naturally when trying to iterate

package/assignGingerly.ts

@@ -506,9 +506,10 @@ export function evaluatePathWithMethods(
   value: any,
   withMethods: Set<string>,
   permissionProcessor?: PermissionProcessor
-): { target: any; lastKey: string; isMethod: boolean; isZeroArg: boolean } {
+): { target: any; lastKey: string; isMethod: boolean; isZeroArg: boolean; lastSegmentConsumed: boolean } {
   let current = target;
   let i = 0;
+  let lastSegmentConsumed = false;
   
   // Process all segments except the last one
   while (i < pathParts.length - 1) {
@@ -533,6 +534,9 @@ export function evaluatePathWithMethods(
           // Only current is method - call with next part as string arg
           current = method.call(current, nextPart, ...appendArgs);
           i++; // Skip next part since we consumed it as argument
+          if (i === pathParts.length - 1) {
+            lastSegmentConsumed = true;
+          }
         }
       } else {
         // Not a function - just access property (create if needed)
@@ -561,7 +565,8 @@ export function evaluatePathWithMethods(
     target: current,
     lastKey,
     isMethod: isAllowedMethod(lastKey, withMethods, permissionProcessor),
-    isZeroArg
+    isZeroArg,
+    lastSegmentConsumed
   };
 }
 
@@ -724,6 +729,110 @@ function applyToEach(
   }
 }
 
+/**
+ * Resolve the RHS of a toggle (=!) command to the value that should be negated.
+ * Supports:
+ * - '?.path' nested path strings resolved against target (returns the resolved value, or true if missing)
+ * - plain key strings looked up on target (returns the value, or true if missing)
+ * - resolved literal values (e.g., booleans from assignFrom) returned as-is
+ */
+function resolveValueToNegate(rhsPath: any, target: any): any {
+  if (typeof rhsPath === 'string' && isNestedPath(rhsPath)) {
+    const rhsPathParts = parsePath(rhsPath);
+    let current = target;
+    let exists = true;
+    for (const part of rhsPathParts) {
+      if (current && typeof current === 'object' && part in current) {
+        current = current[part];
+      } else {
+        exists = false;
+        break;
+      }
+    }
+    return exists ? current : true;
+  }
+  if (typeof rhsPath === 'string') {
+    return (rhsPath in target) ? target[rhsPath] : true;
+  }
+  // Non-string resolved value (e.g., boolean, number, null from assignFrom)
+  return rhsPath;
+}
+
+/**
+ * Navigate a path that leads to an iterable, returning the iterable value or undefined.
+ * Handles withMethods and the evaluatePathWithMethods semantics.
+ */
+function getIterableAtPath(
+  target: any,
+  pathParts: string[],
+  value: any,
+  withMethods: Set<string> | undefined,
+  permissionProcessor?: PermissionProcessor
+): any {
+  let current = target;
+  if (pathParts.length > 0) {
+    if (withMethods && withMethods.size > 0) {
+      const result = evaluatePathWithMethods(target, pathParts, value, withMethods, permissionProcessor);
+      // evaluatePathWithMethods returns the container object + last key by default.
+      // If the last segment was consumed as a method argument, or the last segment
+      // is a zero-arg method marked with |, result.target is already the value.
+      if (result.lastSegmentConsumed) {
+        current = result.target;
+      } else if (result.isMethod) {
+        const method = result.target[result.lastKey];
+        if (typeof method === 'function') {
+          const appendArgs = permissionProcessor?.getMethodAppendArgs(result.lastKey) ?? [];
+          current = method.call(result.target, ...appendArgs);
+        } else {
+          current = method;
+        }
+      } else {
+        current = result.target[result.lastKey];
+      }
+    } else {
+      for (const part of pathParts) {
+        current = current[part];
+      }
+    }
+  }
+  return isIterable(current) ? current : undefined;
+}
+
+/**
+ * Apply an operator command (+=, =!, -=, Y=) to each item in an iterable.
+ * Detects @each in the path, navigates to the iterable, then builds a synthetic
+ * command key for the remaining path and delegates to assignGingerly per item.
+ * Nested @each is handled recursively through assignGingerly.
+ */
+function applyCommandToEach(
+  target: any,
+  pathParts: string[],
+  commandSuffix: string,
+  value: any,
+  withMethods: Set<string> | undefined,
+  aliasMap: Map<string, string>,
+  options?: IAssignGingerlyOptions,
+  permissionProcessor?: PermissionProcessor
+): void {
+  const forEachIndex = pathParts.findIndex(part => isForEachSymbol(part, aliasMap));
+  if (forEachIndex === -1) return;
+
+  const pathToForEach = pathParts.slice(0, forEachIndex);
+  const pathAfterForEach = pathParts.slice(forEachIndex + 1);
+
+  const iterable = getIterableAtPath(target, pathToForEach, value, withMethods, permissionProcessor);
+  if (!iterable) return;
+
+  const items = Array.isArray(iterable) ? iterable : Array.from(iterable);
+  const syntheticKey = pathAfterForEach.length > 0
+    ? `?.${pathAfterForEach.join('?.')}${commandSuffix}`
+    : commandSuffix;
+
+  for (const item of items) {
+    assignGingerly(item, { [syntheticKey]: value }, options, permissionProcessor);
+  }
+}
+
 /**
  * Apply alias substitutions to a key string.
  * Replaces complete tokens between `?.` delimiters with their aliased values.
@@ -845,6 +954,12 @@ export function assignGingerly(
         if (isNestedPath(path)) {
           const pathParts = parsePath(path);
 
+          // Check for @each in path
+          if (pathParts.some(part => isForEachSymbol(part, aliasMap))) {
+            applyCommandToEach(target, pathParts, ' +=', value, withMethodsSet, aliasMap, options, permissionProcessor);
+            continue;
+          }
+
           // Check for withMethods path evaluation
           let lhsValue: any;
           let lhsParent: any;
@@ -915,52 +1030,51 @@ export function assignGingerly(
       const lhsPath = parseToggleCommand(key);
       if (lhsPath) {
         const rhsPath = value;
-        
-        // Resolve LHS
-        let lhsParent: any;
-        let lhsLastKey: string;
+
         if (isNestedPath(lhsPath)) {
           const lhsPathParts = parsePath(lhsPath);
-          lhsLastKey = lhsPathParts[lhsPathParts.length - 1];
-          lhsParent = ensureNestedPath(target, lhsPathParts);
-        } else {
-          lhsLastKey = lhsPath;
-          lhsParent = target;
-        }
 
-        // Determine what to negate
-        let valueToNegate;
-        if (rhsPath === '.') {
-          // Self-reference: negate the LHS value itself (if it exists)
-          if (lhsLastKey in lhsParent) {
-            valueToNegate = lhsParent[lhsLastKey];
+          // Check for @each in the LHS path
+          if (lhsPathParts.some(part => isForEachSymbol(part, aliasMap))) {
+            // Resolve non-self-referencing RHS paths against the original target
+            // before iterating, so each item negates the same root value.
+            const resolvedValue = (rhsPath === '.' || typeof rhsPath !== 'string')
+              ? rhsPath
+              : resolveValueToNegate(rhsPath, target);
+            applyCommandToEach(target, lhsPathParts, ' =!', resolvedValue, withMethodsSet, aliasMap, options, permissionProcessor);
+            continue;
+          }
+
+          // No @each in path - standard toggle
+          const lhsLastKey = lhsPathParts[lhsPathParts.length - 1];
+          const lhsParent = ensureNestedPath(target, lhsPathParts);
+
+          // Determine what to negate
+          let valueToNegate: any;
+          if (rhsPath === '.') {
+            valueToNegate = (lhsLastKey in lhsParent) ? lhsParent[lhsLastKey] : undefined;
           } else {
-            valueToNegate = undefined;
+            valueToNegate = resolveValueToNegate(rhsPath, target);
+          }
+
+          if (!permissionProcessor?.checkRestrictedProp(lhsLastKey)) {
+            lhsParent[lhsLastKey] = !valueToNegate;
           }
         } else {
-          // RHS path: navigate to get the value (don't create paths)
-          if (isNestedPath(rhsPath)) {
-            const rhsPathParts = parsePath(rhsPath);
-            let current = target;
-            let exists = true;
-            for (const part of rhsPathParts) {
-              if (current && typeof current === 'object' && part in current) {
-                current = current[part];
-              } else {
-                exists = false;
-                break;
-              }
-            }
-            valueToNegate = exists ? current : true;
+          // Plain key LHS
+          const lhsLastKey = lhsPath;
+          const lhsParent = target;
+
+          let valueToNegate: any;
+          if (rhsPath === '.') {
+            valueToNegate = (lhsLastKey in lhsParent) ? lhsParent[lhsLastKey] : undefined;
           } else {
-            // Plain key RHS
-            valueToNegate = (rhsPath in target) ? target[rhsPath] : true;
+            valueToNegate = resolveValueToNegate(rhsPath, target);
+          }
+
+          if (!permissionProcessor?.checkRestrictedProp(lhsLastKey)) {
+            lhsParent[lhsLastKey] = !valueToNegate;
           }
-        }
-        
-        // Apply negation to LHS — check restriction first
-        if (!permissionProcessor?.checkRestrictedProp(lhsLastKey)) {
-          lhsParent[lhsLastKey] = !valueToNegate;
         }
       }
       continue;
@@ -976,6 +1090,13 @@ export function assignGingerly(
         
         if (isNestedPath(path)) {
           const pathParts = parsePath(path);
+
+          // Check for @each in path
+          if (pathParts.some(part => isForEachSymbol(part, aliasMap))) {
+            applyCommandToEach(target, pathParts, ' -=', value, withMethodsSet, aliasMap, options, permissionProcessor);
+            continue;
+          }
+
           if (pathParts.length === 0) {
             parent = target;
           } else {
@@ -1019,6 +1140,13 @@ export function assignGingerly(
         if (permissionProcessor?.checkRestrictedProp(lastKey)) {
           continue;
         }
+
+        // Check for @each in path
+        if (isNestedPath(path) && pathParts.some(part => isForEachSymbol(part, aliasMap))) {
+          applyCommandToEach(target, pathParts, ' Y=', value, withMethodsSet, aliasMap, options, permissionProcessor);
+          continue;
+        }
+
         // Navigate to the target sub-object
         let mergeTarget: any;
         if (isNestedPath(path)) {
@@ -1086,24 +1214,12 @@ export function assignGingerly(
         // 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, permissionProcessor);
-            // 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];
-            }
-          }
-        }
-        
+        const current = getIterableAtPath(target, pathToForEach, value, withMethodsSet, permissionProcessor);
+
         // Apply to each item in the iterable
-        if (isIterable(current)) {
+        if (current) {
           applyToEach(current, pathAfterForEach, value, withMethodsSet || new Set(), aliasMap, options, permissionProcessor);
         }
         // If not iterable, let JavaScript throw error naturally when trying to iterate

package/handleIshProperty.js

@@ -47,7 +47,7 @@ async function defineIshProperty(element, managerName, options, assignGingerlyFn
     let config = registry.get(managerName);
     // If not registered, wait for registration
     if (!config) {
-        const { waitForEvent } = await import('./waitForEvent.js');
+        const { waitForEvent } = await import('./utils/waitForEvent.js');
         await waitForEvent(registry, managerName);
         config = registry.get(managerName);
         if (!config) {

package/handleIshProperty.ts

@@ -66,7 +66,7 @@ async function defineIshProperty(
 
   // If not registered, wait for registration
   if (!config) {
-    const { waitForEvent } = await import('./waitForEvent.js');
+    const { waitForEvent } = await import('./utils/waitForEvent.js');
     await waitForEvent(registry, managerName);
     config = registry.get(managerName);
     

package/handlers/manageTemplateList.js

@@ -224,7 +224,7 @@ export class ManageTemplateListHandler {
         if (fragment.childNodes.length > 0) {
             const waitOpt = resolvedParams.waitForSettled;
             if (waitOpt) {
-                const { waitForSettled } = await import('../waitForSettled.js');
+                const { waitForSettled } = await import('../utils/waitForSettled.js');
                 const idleMs = typeof waitOpt === 'object' ? waitOpt.idleMs : 100;
                 const timeout = typeof waitOpt === 'object' ? waitOpt.timeout : undefined;
                 try {

package/handlers/manageTemplateList.ts

@@ -263,7 +263,7 @@ export class ManageTemplateListHandler implements AssignFromHandler {
         if (fragment.childNodes.length > 0) {
             const waitOpt = resolvedParams.waitForSettled;
             if (waitOpt) {
-                const { waitForSettled } = await import('../waitForSettled.js');
+                const { waitForSettled } = await import('../utils/waitForSettled.js');
                 const idleMs = typeof waitOpt === 'object' ? waitOpt.idleMs : 100;
                 const timeout = typeof waitOpt === 'object' ? waitOpt.timeout : undefined;
                 try {

package/index.js

@@ -1,7 +1,7 @@
 export { assignGingerly } from './assignGingerly.js';
 export { assignTentatively } from './assignTentatively.js';
 export { EnhancementRegistry, ItemscopeRegistry, EnhancementRegisteredEvent } from './assignGingerly.js';
-export { waitForEvent } from './waitForEvent.js';
+export { waitForEvent } from './utils/waitForEvent.js';
 export { ParserRegistry, globalParserRegistry } from './parserRegistry.js';
 export { parseWithAttrs } from './parseWithAttrs.js';
 export { buildCSSQuery } from './buildCSSQuery.js';

package/index.ts

@@ -1,7 +1,7 @@
 export {assignGingerly} from './assignGingerly.js';
 export {assignTentatively} from './assignTentatively.js';
 export {EnhancementRegistry, ItemscopeRegistry, EnhancementRegisteredEvent} from './assignGingerly.js';
-export {waitForEvent} from './waitForEvent.js';
+export {waitForEvent} from './utils/waitForEvent.js';
 export {ParserRegistry, globalParserRegistry} from './parserRegistry.js';
 export {parseWithAttrs} from './parseWithAttrs.js';
 export {buildCSSQuery} from './buildCSSQuery.js';

package/inferencer/types/roundabout/types.d.ts

@@ -53,6 +53,7 @@ export type Compacts<TProps = any, TActions = TProps, TEvents extends string = s
     | Partial<{[key in `when_${keyof TProps & string}_changes_dispatch`]: string}>
     | Partial<{[key in `on_${TEvents}_of_${keyof TProps & string}_inc_${keyof TProps & string}_by`]: number}>
     | Partial<{[key in `on_${TEvents}_of_${keyof TProps & string}_set_${keyof TProps & string}_to`]: any}>
+    | Partial<{[key in `on_${TEvents}_of_${keyof TProps & string}_assign`]: Record<string, any>}>
 ;
 
 export type Hitches<TProps = any, TActions = TProps> = 

package/object-extension.js

@@ -250,7 +250,7 @@ class ElementEnhancementContainer {
             throw new Error('Instance must be an EventTarget to use whenResolved');
         }
         // Lazy load waitForEvent
-        const { waitForEvent } = await import('./waitForEvent.js');
+        const { waitForEvent } = await import('./utils/waitForEvent.js');
         // Wait for the resolved event (use resolvedKey as event name)
         // Note: When symbols are supported as event names, this will work with symbol keys too
         await waitForEvent(spawnedInstance, resolvedKey);

package/object-extension.ts

@@ -359,7 +359,7 @@ class ElementEnhancementContainer {
     }
     
     // Lazy load waitForEvent
-    const { waitForEvent } = await import('./waitForEvent.js');
+    const { waitForEvent } = await import('./utils/waitForEvent.js');
     
     // Wait for the resolved event (use resolvedKey as event name)
     // Note: When symbols are supported as event names, this will work with symbol keys too

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.79",
+  "version": "0.0.80",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {
@@ -159,9 +159,9 @@
       "default": "./markerUtils.js",
       "types": "./markerUtils.ts"
     },
-    "./waitForSettled.js": {
-      "default": "./waitForSettled.js",
-      "types": "./waitForSettled.ts"
+    "./utils/waitForSettled.js": {
+      "default": "./utils/waitForSettled.js",
+      "types": "./utils/waitForSettled.ts"
     },
     "./inferredAssignments.js": {
       "default": "./inferredAssignments.js",
@@ -199,8 +199,9 @@
       "default": "./evaluatePathWithAsyncMethods.js",
       "types": "./evaluatePathWithAsyncMethods.ts"
     },
-    "./waitForEvent.js": {
-      "default": "./waitForEvent.js"
+    "./utils/waitForEvent.js": {
+      "default": "./utils/waitForEvent.js",
+      "types": "./utils/waitForEvent.ts"
     }
   },
   "main": "index.js",