assign-gingerly 0.0.33 → 0.0.35

package/README.md

@@ -734,7 +734,7 @@ console.log(obj);
 // }
 ```
 
-The `+=` command syntax is `<path> +=` where the path can use the `?.` nested notation. The right-hand side value is added to the existing value using `+=`. If the path doesn't exist, it's created and set directly to the value.  If the expression is a string, string concatenation is used.  If the expression can't be "added to", it allows JavaScript to throw its natural error.
+The `+=` command syntax is `<path> +=` where the path uses the `?.` nested notation for nested properties, or a plain key for direct properties. The right-hand side value is added to the existing value using `+=`. If the path doesn't exist, it's created and set directly to the value.  If the expression is a string, string concatenation is used.  If the expression can't be "added to", it allows JavaScript to throw its natural error.
 
 ## Example 5 - Toggling boolean values and negating
 
@@ -764,7 +764,7 @@ console.log(obj);
 // }
 ```
 
-The `=!` command syntax is `<path> =!` where the path can use the `?.` nested notation. 
+The `=!` command syntax is `<path> =!` where the path uses the `?.` nested notation for nested properties, or a plain key for direct properties.
 
 For existing values, the toggle is performed using JavaScript's logical NOT operator (`!value`), regardless of what type it is.
 
@@ -3303,6 +3303,28 @@ console.log(result);
 
 -->
 
+## Resolving and Assigning with `assignFrom`
+
+The `assignFrom` function combines RHS path resolution with `assignGingerly` in a single call. It resolves `?.`-prefixed RHS values against a source object, then assigns the results into a target. Use `?.` alone as a RHS value to reference the entire source object itself.
+
+```TypeScript
+import { assignFrom } from 'assign-gingerly/assignFrom.js';
+
+const viewModel = { username: 'Alice', clone: someDocumentFragment };
+
+assignFrom(target, {
+  '?.appendChild': '?..clone',                              // source.clone
+  '?.clone?.q?..username?.textContent': '?.username',       // source.username
+  ref: '?.'                                                  // the source object itself
+}, {
+  from: viewModel,
+  withMethods: ['appendChild'],
+  aka: { 'q': 'querySelector' }
+});
+```
+
+For full documentation, see [docs/assignFrom.md](docs/assignFrom.md).
+
 ## Itemscope Managers (Chrome 146+)
 
 Itemscope Managers provide a way to manage DOM fragments and their associated data/view models for elements with the `itemscope` attribute. This feature enables frameworks and libraries to manage light children of web components, DOM fragments from looping constructs, and scenarios where custom element wrapping is not feasible.

package/assignGingerly.js

@@ -201,11 +201,13 @@ function parseDeleteCommand(key) {
 }
 /**
  * Helper function to parse a path string with ?. notation
+ * Always splits on '?.' delimiter, preserving dots that are part of values
+ * (e.g., CSS class selectors like '.username')
+ * Paths must use ?. notation — plain dot notation is not supported.
  */
 function parsePath(path) {
     return path
-        .split('.')
-        .map(part => part.replace(/\?/g, ''))
+        .split('?.')
         .filter(part => part.length > 0);
 }
 /**
@@ -572,16 +574,25 @@ export function assignGingerly(target, source, options) {
         if (isIncCommand(key)) {
             const path = parseIncCommand(key);
             if (path) {
-                const pathParts = parsePath(path);
-                const lastKey = pathParts[pathParts.length - 1];
-                const parent = ensureNestedPath(target, pathParts);
-                // If the path doesn't exist, set it directly to the value
-                if (!(lastKey in parent)) {
-                    parent[lastKey] = value;
+                if (isNestedPath(path)) {
+                    const pathParts = parsePath(path);
+                    const lastKey = pathParts[pathParts.length - 1];
+                    const parent = ensureNestedPath(target, pathParts);
+                    if (!(lastKey in parent)) {
+                        parent[lastKey] = value;
+                    }
+                    else {
+                        parent[lastKey] += value;
+                    }
                 }
                 else {
-                    // Path exists, apply increment: oldValue += newValue
-                    parent[lastKey] += value;
+                    // Plain key - direct operation on target
+                    if (!(path in target)) {
+                        target[path] = value;
+                    }
+                    else {
+                        target[path] += value;
+                    }
                 }
             }
             continue;
@@ -591,10 +602,18 @@ export function assignGingerly(target, source, options) {
             const lhsPath = parseToggleCommand(key);
             if (lhsPath) {
                 const rhsPath = value;
-                // Parse LHS path
-                const lhsPathParts = parsePath(lhsPath);
-                const lhsLastKey = lhsPathParts[lhsPathParts.length - 1];
-                const lhsParent = ensureNestedPath(target, lhsPathParts);
+                // 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 === '.') {
@@ -603,26 +622,30 @@ export function assignGingerly(target, source, options) {
                         valueToNegate = lhsParent[lhsLastKey];
                     }
                     else {
-                        // LHS doesn't exist, treat as undefined -> !undefined = true
                         valueToNegate = undefined;
                     }
                 }
                 else {
                     // RHS path: navigate to get the value (don't create paths)
-                    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;
+                    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;
+                    }
+                    else {
+                        // Plain key RHS
+                        valueToNegate = (rhsPath in target) ? target[rhsPath] : true;
                     }
-                    // If RHS doesn't exist, treat as truthy (will become false)
-                    valueToNegate = exists ? current : true;
                 }
                 // Apply negation to LHS
                 lhsParent[lhsLastKey] = !valueToNegate;
@@ -633,28 +656,37 @@ export function assignGingerly(target, source, options) {
         if (isDeleteCommand(key)) {
             const path = parseDeleteCommand(key);
             if (path !== null) {
-                const pathParts = parsePath(path);
                 // Determine the parent object
                 let parent = target;
                 let canDelete = true;
-                // If path is empty or just '?', delete from root
-                if (pathParts.length === 0) {
-                    parent = target;
-                }
-                else {
-                    // Navigate to parent object
-                    for (const part of pathParts) {
-                        if (parent && typeof parent === 'object' && part in parent) {
-                            parent = parent[part];
-                        }
-                        else {
-                            canDelete = false;
-                            break;
+                if (isNestedPath(path)) {
+                    const pathParts = parsePath(path);
+                    if (pathParts.length === 0) {
+                        parent = target;
+                    }
+                    else {
+                        for (const part of pathParts) {
+                            if (parent && typeof parent === 'object' && part in parent) {
+                                parent = parent[part];
+                            }
+                            else {
+                                canDelete = false;
+                                break;
+                            }
                         }
                     }
                 }
+                else if (path.length > 0) {
+                    // Plain key - navigate one level
+                    if (parent && typeof parent === 'object' && path in parent) {
+                        parent = parent[path];
+                    }
+                    else {
+                        canDelete = false;
+                    }
+                }
+                // else: empty path = delete from root
                 if (canDelete && typeof parent === 'object' && parent !== null) {
-                    // RHS can be a string (single property) or array (multiple properties)
                     const propertiesToDelete = Array.isArray(value) ? value : [value];
                     for (const prop of propertiesToDelete) {
                         if (prop in parent) {

package/assignGingerly.ts

@@ -326,11 +326,13 @@ function parseDeleteCommand(key: string): string | null {
 
 /**
  * Helper function to parse a path string with ?. notation
+ * Always splits on '?.' delimiter, preserving dots that are part of values
+ * (e.g., CSS class selectors like '.username')
+ * Paths must use ?. notation — plain dot notation is not supported.
  */
 function parsePath(path: string): string[] {
   return path
-    .split('.')
-    .map(part => part.replace(/\?/g, ''))
+    .split('?.')
     .filter(part => part.length > 0);
 }
 
@@ -736,16 +738,22 @@ export function assignGingerly(
     if (isIncCommand(key)) {
       const path = parseIncCommand(key);
       if (path) {
-        const pathParts = parsePath(path);
-        const lastKey = pathParts[pathParts.length - 1];
-        const parent = ensureNestedPath(target, pathParts);
-
-        // If the path doesn't exist, set it directly to the value
-        if (!(lastKey in parent)) {
-          parent[lastKey] = value;
+        if (isNestedPath(path)) {
+          const pathParts = parsePath(path);
+          const lastKey = pathParts[pathParts.length - 1];
+          const parent = ensureNestedPath(target, pathParts);
+          if (!(lastKey in parent)) {
+            parent[lastKey] = value;
+          } else {
+            parent[lastKey] += value;
+          }
         } else {
-          // Path exists, apply increment: oldValue += newValue
-          parent[lastKey] += value;
+          // Plain key - direct operation on target
+          if (!(path in target)) {
+            target[path] = value;
+          } else {
+            target[path] += value;
+          }
         }
       }
       continue;
@@ -757,10 +765,17 @@ export function assignGingerly(
       if (lhsPath) {
         const rhsPath = value;
         
-        // Parse LHS path
-        const lhsPathParts = parsePath(lhsPath);
-        const lhsLastKey = lhsPathParts[lhsPathParts.length - 1];
-        const lhsParent = ensureNestedPath(target, lhsPathParts);
+        // 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;
@@ -769,26 +784,27 @@ export function assignGingerly(
           if (lhsLastKey in lhsParent) {
             valueToNegate = lhsParent[lhsLastKey];
           } else {
-            // LHS doesn't exist, treat as undefined -> !undefined = true
             valueToNegate = undefined;
           }
         } else {
           // RHS path: navigate to get the value (don't create paths)
-          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;
+          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;
+          } else {
+            // Plain key RHS
+            valueToNegate = (rhsPath in target) ? target[rhsPath] : true;
           }
-          
-          // If RHS doesn't exist, treat as truthy (will become false)
-          valueToNegate = exists ? current : true;
         }
         
         // Apply negation to LHS
@@ -801,31 +817,36 @@ export function assignGingerly(
     if (isDeleteCommand(key)) {
       const path = parseDeleteCommand(key);
       if (path !== null) {
-        const pathParts = parsePath(path);
-        
         // Determine the parent object
         let parent = target;
         let canDelete = true;
         
-        // If path is empty or just '?', delete from root
-        if (pathParts.length === 0) {
-          parent = target;
-        } else {
-          // Navigate to parent object
-          for (const part of pathParts) {
-            if (parent && typeof parent === 'object' && part in parent) {
-              parent = parent[part];
-            } else {
-              canDelete = false;
-              break;
+        if (isNestedPath(path)) {
+          const pathParts = parsePath(path);
+          if (pathParts.length === 0) {
+            parent = target;
+          } else {
+            for (const part of pathParts) {
+              if (parent && typeof parent === 'object' && part in parent) {
+                parent = parent[part];
+              } else {
+                canDelete = false;
+                break;
+              }
             }
           }
+        } else if (path.length > 0) {
+          // Plain key - navigate one level
+          if (parent && typeof parent === 'object' && path in parent) {
+            parent = parent[path];
+          } else {
+            canDelete = false;
+          }
         }
+        // else: empty path = delete from root
         
         if (canDelete && typeof parent === 'object' && parent !== null) {
-          // RHS can be a string (single property) or array (multiple properties)
           const propertiesToDelete = Array.isArray(value) ? value : [value];
-          
           for (const prop of propertiesToDelete) {
             if (prop in parent) {
               delete parent[prop];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.33",
+  "version": "0.0.35",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {

package/resolveValues.js

@@ -26,8 +26,10 @@ export function resolveValues(pattern, source) {
     const result = {};
     for (const [key, value] of Object.entries(pattern)) {
         if (typeof value === 'string' && value.startsWith('?.')) {
-            // Parse path: split by '.', strip '?', filter empties
-            const parts = value.split('.').map(p => p.replace(/\?/g, '')).filter(p => p.length > 0);
+            // Parse path: split on '?.' delimiter, filter empties
+            // Use '?.' as the sole delimiter to preserve dots in values (e.g., CSS selectors)
+            // Special case: '?.' alone (empty path) resolves to the source object itself
+            const parts = value.split('?.').filter(p => p.length > 0);
             let current = source;
             for (const part of parts) {
                 if (current == null)

package/resolveValues.ts

@@ -29,8 +29,10 @@ export function resolveValues(
   const result: Record<string, any> = {};
   for (const [key, value] of Object.entries(pattern)) {
     if (typeof value === 'string' && value.startsWith('?.')) {
-      // Parse path: split by '.', strip '?', filter empties
-      const parts = value.split('.').map(p => p.replace(/\?/g, '')).filter(p => p.length > 0);
+      // Parse path: split on '?.' delimiter, filter empties
+      // Use '?.' as the sole delimiter to preserve dots in values (e.g., CSS selectors)
+      // Special case: '?.' alone (empty path) resolves to the source object itself
+      const parts = value.split('?.').filter(p => p.length > 0);
       let current = source;
       for (const part of parts) {
         if (current == null) break;