assign-gingerly 0.0.31 → 0.0.32

package/eachTime.js

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

package/eachTime.ts

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

package/index.js

@@ -7,4 +7,6 @@ export { parseWithAttrs } from './parseWithAttrs.js';
 export { buildCSSQuery } from './buildCSSQuery.js';
 export { resolveTemplate } from './resolveTemplate.js';
 export { getHost } from './getHost.js';
+export { resolveValues } from './resolveValues.js';
+export { assignFrom } from './assignFrom.js';
 import './object-extension.js';

package/index.ts

@@ -7,4 +7,6 @@ export {parseWithAttrs} from './parseWithAttrs.js';
 export {buildCSSQuery} from './buildCSSQuery.js';
 export {resolveTemplate} from './resolveTemplate.js';
 export {getHost} from './getHost.js';
+export {resolveValues} from './resolveValues.js';
+export {assignFrom} from './assignFrom.js';
 import './object-extension.js';

package/object-extension.js

@@ -64,9 +64,27 @@ class ElementEnhancementContainer {
     constructor(element) {
         this.element = element;
     }
+    /**
+     * Resolve a registryItem parameter to an EnhancementConfig.
+     * If a string or symbol is passed, looks it up via findByEnhKey in the registry.
+     * @param registryItem - EnhancementConfig object, or string/symbol enhKey
+     * @param registry - The enhancement registry to search
+     * @returns The resolved EnhancementConfig
+     * @throws Error if string/symbol not found in registry
+     */
+    resolveRegistryItem(registryItem, registry) {
+        if (typeof registryItem === 'string' || typeof registryItem === 'symbol') {
+            const found = registry.findByEnhKey(registryItem);
+            if (!found) {
+                throw new Error(`${String(registryItem)} not in registry`);
+            }
+            return found;
+        }
+        return registryItem;
+    }
     /**
      * Get or spawn an instance for a registry item
-     * @param registryItem - The registry item to get/spawn instance for
+     * @param registryItem - The registry item (EnhancementConfig object, or string/symbol enhKey) to get/spawn instance for
      * @param mountCtx - Optional context to pass to the spawned instance
      * @returns The spawned instance
      */
@@ -77,6 +95,8 @@ class ElementEnhancementContainer {
         if (!registry) {
             throw new Error('customElementRegistry.enhancementRegistry not available');
         }
+        // Resolve string/symbol to EnhancementConfig via enhKey lookup
+        registryItem = this.resolveRegistryItem(registryItem, registry);
         // Check if registryItem is in the registry
         const items = registry.getItems();
         if (!items.includes(registryItem)) {
@@ -109,7 +129,7 @@ class ElementEnhancementContainer {
                         mountCtx,
                         synthesizerElement: mountCtx?.synthesizerElement
                     };
-                    attrInitVals = parseWithAttrs(element, registryItem.withAttrs, registryItem.allowUnprefixed || false, spawnContext);
+                    attrInitVals = parseWithAttrs(element, registryItem.withAttrs, registryItem.allowUnprefixed, spawnContext);
                 }
                 catch (e) {
                     console.error('Error parsing attributes:', e);
@@ -145,48 +165,81 @@ class ElementEnhancementContainer {
     }
     /**
      * Dispose of an enhancement instance
-     * @param registryItem - The registry item to dispose
+     * @param registryItem - The registry item (EnhancementConfig object, or string/symbol enhKey) to dispose
      */
     dispose(registryItem) {
         const element = this.element;
+        // Resolve string/symbol to EnhancementConfig via enhKey lookup
+        let resolved;
+        if (typeof registryItem === 'string' || typeof registryItem === 'symbol') {
+            const registry = element.customElementRegistry?.enhancementRegistry;
+            if (!registry) {
+                return; // No registry, nothing to dispose
+            }
+            const found = registry.findByEnhKey(registryItem);
+            if (!found) {
+                throw new Error(`${String(registryItem)} not in registry`);
+            }
+            resolved = found;
+        }
+        else {
+            resolved = registryItem;
+        }
         // Get the instance map
         const instanceMap = getInstanceMap();
         if (!instanceMap.has(element)) {
             return; // No instances for this element
         }
         const instances = instanceMap.get(element);
-        const spawnedInstance = instances.get(registryItem);
+        const spawnedInstance = instances.get(resolved);
         if (!spawnedInstance) {
             return; // No instance for this registry item
         }
         // Call dispose lifecycle method if it exists
-        const lifecycleKeys = normalizeLifecycleKeys(registryItem?.lifecycleKeys);
+        const lifecycleKeys = normalizeLifecycleKeys(resolved.lifecycleKeys);
         const disposeKey = lifecycleKeys?.dispose;
         if (disposeKey && typeof spawnedInstance[disposeKey] === 'function') {
-            spawnedInstance[disposeKey](registryItem);
+            spawnedInstance[disposeKey](resolved);
         }
         // Remove from instance map
-        instances.delete(registryItem);
+        instances.delete(resolved);
         // Remove from enh container if it has an enhKey
-        if (registryItem.enhKey) {
+        if (resolved.enhKey) {
             const self = this;
-            delete self[registryItem.enhKey];
+            delete self[resolved.enhKey];
         }
     }
     /**
      * Wait for an enhancement instance to be resolved
-     * @param registryItem - The registry item to wait for
+     * @param registryItem - The registry item (EnhancementConfig object, or string/symbol enhKey) to wait for
      * @param mountCtx - Optional context to pass to the spawned instance
      * @returns Promise that resolves with the spawned instance
      */
     async whenResolved(registryItem, mountCtx) {
-        const lifecycleKeys = normalizeLifecycleKeys(registryItem?.lifecycleKeys);
+        // Resolve string/symbol to EnhancementConfig via enhKey lookup
+        let resolved;
+        if (typeof registryItem === 'string' || typeof registryItem === 'symbol') {
+            const element = this.element;
+            const registry = element.customElementRegistry?.enhancementRegistry;
+            if (!registry) {
+                throw new Error('customElementRegistry.enhancementRegistry not available');
+            }
+            const found = registry.findByEnhKey(registryItem);
+            if (!found) {
+                throw new Error(`${String(registryItem)} not in registry`);
+            }
+            resolved = found;
+        }
+        else {
+            resolved = registryItem;
+        }
+        const lifecycleKeys = normalizeLifecycleKeys(resolved.lifecycleKeys);
         const resolvedKey = lifecycleKeys?.resolved;
         if (resolvedKey === undefined) {
             throw new Error('Must specify resolved key in lifecycleKeys');
         }
         // Get or spawn the instance (pass mountCtx through)
-        const spawnedInstance = this.get(registryItem, mountCtx);
+        const spawnedInstance = this.get(resolved, mountCtx);
         // Check if already resolved
         if (spawnedInstance[resolvedKey]) {
             return spawnedInstance;

package/object-extension.ts

@@ -1,4 +1,5 @@
 import assignGingerly, { EnhancementRegistry, ItemscopeRegistry, IAssignGingerlyOptions, getInstanceMap, INSTANCE_MAP_GUID } from './assignGingerly.js';
+import { EnhancementConfig } from './types/assign-gingerly/types.js';
 import { parseWithAttrs } from './parseWithAttrs.js';
 
 /**
@@ -132,13 +133,35 @@ class ElementEnhancementContainer {
     this.element = element;
   }
 
+  /**
+   * Resolve a registryItem parameter to an EnhancementConfig.
+   * If a string or symbol is passed, looks it up via findByEnhKey in the registry.
+   * @param registryItem - EnhancementConfig object, or string/symbol enhKey
+   * @param registry - The enhancement registry to search
+   * @returns The resolved EnhancementConfig
+   * @throws Error if string/symbol not found in registry
+   */
+  private resolveRegistryItem(
+    registryItem: EnhancementConfig | string | symbol,
+    registry: EnhancementRegistry
+  ): EnhancementConfig {
+    if (typeof registryItem === 'string' || typeof registryItem === 'symbol') {
+      const found = registry.findByEnhKey(registryItem);
+      if (!found) {
+        throw new Error(`${String(registryItem)} not in registry`);
+      }
+      return found;
+    }
+    return registryItem;
+  }
+
   /**
    * Get or spawn an instance for a registry item
-   * @param registryItem - The registry item to get/spawn instance for
+   * @param registryItem - The registry item (EnhancementConfig object, or string/symbol enhKey) to get/spawn instance for
    * @param mountCtx - Optional context to pass to the spawned instance
    * @returns The spawned instance
    */
-  get(registryItem: any, mountCtx?: any): any {
+  get(registryItem: EnhancementConfig | string | symbol, mountCtx?: any): any {
     const element = this.element;
     
     // Get the registry from customElementRegistry
@@ -148,6 +171,9 @@ class ElementEnhancementContainer {
       throw new Error('customElementRegistry.enhancementRegistry not available');
     }
     
+    // Resolve string/symbol to EnhancementConfig via enhKey lookup
+    registryItem = this.resolveRegistryItem(registryItem, registry);
+    
     // Check if registryItem is in the registry
     const items = registry.getItems();
     if (!items.includes(registryItem)) {
@@ -188,7 +214,7 @@ class ElementEnhancementContainer {
           attrInitVals = parseWithAttrs(
             element, 
             registryItem.withAttrs,
-            registryItem.allowUnprefixed || false,
+            registryItem.allowUnprefixed,
             spawnContext
           );
         } catch (e) {
@@ -232,11 +258,27 @@ class ElementEnhancementContainer {
 
   /**
    * Dispose of an enhancement instance
-   * @param registryItem - The registry item to dispose
+   * @param registryItem - The registry item (EnhancementConfig object, or string/symbol enhKey) to dispose
    */
-  dispose(registryItem: any): void {
+  dispose(registryItem: EnhancementConfig | string | symbol): void {
     const element = this.element;
     
+    // Resolve string/symbol to EnhancementConfig via enhKey lookup
+    let resolved: EnhancementConfig;
+    if (typeof registryItem === 'string' || typeof registryItem === 'symbol') {
+      const registry = (element as any).customElementRegistry?.enhancementRegistry;
+      if (!registry) {
+        return; // No registry, nothing to dispose
+      }
+      const found = registry.findByEnhKey(registryItem);
+      if (!found) {
+        throw new Error(`${String(registryItem)} not in registry`);
+      }
+      resolved = found;
+    } else {
+      resolved = registryItem;
+    }
+    
     // Get the instance map
     const instanceMap = getInstanceMap();
     if (!instanceMap.has(element)) {
@@ -244,37 +286,54 @@ class ElementEnhancementContainer {
     }
     
     const instances = instanceMap.get(element)!;
-    const spawnedInstance = instances.get(registryItem);
+    const spawnedInstance = instances.get(resolved);
     
     if (!spawnedInstance) {
       return; // No instance for this registry item
     }
     
     // Call dispose lifecycle method if it exists
-    const lifecycleKeys = normalizeLifecycleKeys(registryItem?.lifecycleKeys);
+    const lifecycleKeys = normalizeLifecycleKeys(resolved.lifecycleKeys);
     const disposeKey = lifecycleKeys?.dispose;
     if (disposeKey && typeof spawnedInstance[disposeKey] === 'function') {
-      spawnedInstance[disposeKey](registryItem);
+      spawnedInstance[disposeKey](resolved);
     }
     
     // Remove from instance map
-    instances.delete(registryItem);
+    instances.delete(resolved);
     
     // Remove from enh container if it has an enhKey
-    if (registryItem.enhKey) {
+    if (resolved.enhKey) {
       const self = this as any;
-      delete self[registryItem.enhKey];
+      delete self[resolved.enhKey];
     }
   }
 
   /**
    * Wait for an enhancement instance to be resolved
-   * @param registryItem - The registry item to wait for
+   * @param registryItem - The registry item (EnhancementConfig object, or string/symbol enhKey) to wait for
    * @param mountCtx - Optional context to pass to the spawned instance
    * @returns Promise that resolves with the spawned instance
    */
-  async whenResolved(registryItem: any, mountCtx?: any): Promise<any> {
-    const lifecycleKeys = normalizeLifecycleKeys(registryItem?.lifecycleKeys);
+  async whenResolved(registryItem: EnhancementConfig | string | symbol, mountCtx?: any): Promise<any> {
+    // Resolve string/symbol to EnhancementConfig via enhKey lookup
+    let resolved: EnhancementConfig;
+    if (typeof registryItem === 'string' || typeof registryItem === 'symbol') {
+      const element = this.element;
+      const registry = (element as any).customElementRegistry?.enhancementRegistry;
+      if (!registry) {
+        throw new Error('customElementRegistry.enhancementRegistry not available');
+      }
+      const found = registry.findByEnhKey(registryItem);
+      if (!found) {
+        throw new Error(`${String(registryItem)} not in registry`);
+      }
+      resolved = found;
+    } else {
+      resolved = registryItem;
+    }
+    
+    const lifecycleKeys = normalizeLifecycleKeys(resolved.lifecycleKeys);
     const resolvedKey = lifecycleKeys?.resolved;
     
     if (resolvedKey === undefined) {
@@ -282,7 +341,7 @@ class ElementEnhancementContainer {
     }
     
     // Get or spawn the instance (pass mountCtx through)
-    const spawnedInstance = this.get(registryItem, mountCtx);
+    const spawnedInstance = this.get(resolved, mountCtx);
     
     // Check if already resolved
     if ((spawnedInstance as any)[resolvedKey]) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.31",
+  "version": "0.0.32",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {
@@ -55,6 +55,14 @@
     "./getHost.js": {
       "default": "./getHost.js",
       "types": "./getHost.ts"
+    },
+    "./resolveValues.js": {
+      "default": "./resolveValues.js",
+      "types": "./resolveValues.ts"
+    },
+    "./assignFrom.js": {
+      "default": "./assignFrom.js",
+      "types": "./assignFrom.ts"
     }
   },
   "main": "index.js",

package/resolveValues.js

@@ -0,0 +1,44 @@
+/**
+ * Resolve RHS path strings in a pattern object against a source object.
+ *
+ * Any value that is a string starting with `?.` is treated as a path
+ * and resolved against the source object using optional chaining semantics.
+ * Non-string values and strings not starting with `?.` pass through unchanged.
+ *
+ * @param pattern - Object whose RHS values may contain `?.` path strings
+ * @param source - Object to resolve paths against
+ * @returns New object with path strings replaced by resolved values
+ *
+ * @example
+ * const pattern = {
+ *   hello: '?.myPropContainer?.stringProp',
+ *   foo: '?.myFooString',
+ *   literal: 42
+ * };
+ * const source = {
+ *   myPropContainer: { stringProp: 'Venus' },
+ *   myFooString: 'bar'
+ * };
+ * const result = resolveValues(pattern, source);
+ * // { hello: 'Venus', foo: 'bar', literal: 42 }
+ */
+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);
+            let current = source;
+            for (const part of parts) {
+                if (current == null)
+                    break;
+                current = current[part];
+            }
+            result[key] = current;
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}

package/resolveValues.ts

@@ -0,0 +1,45 @@
+/**
+ * Resolve RHS path strings in a pattern object against a source object.
+ * 
+ * Any value that is a string starting with `?.` is treated as a path
+ * and resolved against the source object using optional chaining semantics.
+ * Non-string values and strings not starting with `?.` pass through unchanged.
+ * 
+ * @param pattern - Object whose RHS values may contain `?.` path strings
+ * @param source - Object to resolve paths against
+ * @returns New object with path strings replaced by resolved values
+ * 
+ * @example
+ * const pattern = {
+ *   hello: '?.myPropContainer?.stringProp',
+ *   foo: '?.myFooString',
+ *   literal: 42
+ * };
+ * const source = {
+ *   myPropContainer: { stringProp: 'Venus' },
+ *   myFooString: 'bar'
+ * };
+ * const result = resolveValues(pattern, source);
+ * // { hello: 'Venus', foo: 'bar', literal: 42 }
+ */
+export function resolveValues(
+  pattern: Record<string, any>,
+  source: any
+): Record<string, any> {
+  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);
+      let current = source;
+      for (const part of parts) {
+        if (current == null) break;
+        current = current[part];
+      }
+      result[key] = current;
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}