assign-gingerly 0.0.38 → 0.0.39

package/assignGingerly.js

@@ -203,12 +203,21 @@ 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')
+/**
+ * Path cache for parsed path strings in assignGingerly.
+ * Avoids re-splitting the same path on repeated calls.
+ */
+const agPathCache = new Map();
+/**
  * Paths must use ?. notation — plain dot notation is not supported.
  */
 function parsePath(path) {
-    return path
-        .split('?.')
-        .filter(part => part.length > 0);
+    let parts = agPathCache.get(path);
+    if (!parts) {
+        parts = path.split('?.').filter(part => part.length > 0);
+        agPathCache.set(path, parts);
+    }
+    return parts;
 }
 /**
  * Helper function to check if a path starts with ?. notation
@@ -264,6 +273,26 @@ export function isReadonlyProperty(obj, propName) {
     }
     return false;
 }
+/**
+ * Checks if a class defines a static `assignTo` method and calls it.
+ * This is the "bring your own assigner" protocol — classes can opt into
+ * custom assignment behavior by defining `static assignTo`.
+ *
+ * Only triggers for classes that explicitly define `assignTo` on themselves
+ * (not inherited from Object or other base classes).
+ *
+ * @returns true if assignTo was found and called, false otherwise
+ */
+function tryAssignTo(currentValue, value, parent, key) {
+    if (currentValue != null && typeof currentValue === 'object') {
+        const { constructor } = currentValue;
+        if (constructor && Object.hasOwn(constructor, 'assignTo') && typeof constructor.assignTo === 'function') {
+            constructor.assignTo(currentValue, value, parent, key);
+            return true;
+        }
+    }
+    return false;
+}
 /**
  * Helper function to check if a value is a class instance (not a plain object)
  * Returns true for instances of classes, false for plain objects, arrays, and primitives
@@ -496,6 +525,12 @@ export function assignGingerly(target, source, options) {
             ? options.withMethods
             : new Set(options.withMethods)
         : undefined;
+    // Convert withAsyncMethods array to Set for O(1) lookup
+    const withAsyncMethodsSet = options?.withAsyncMethods
+        ? options.withAsyncMethods instanceof Set
+            ? options.withAsyncMethods
+            : new Set(options.withAsyncMethods)
+        : undefined;
     // Convert aka object to Map for O(1) lookup and validate aliases
     const aliasMap = new Map();
     if (options?.aka) {
@@ -743,6 +778,52 @@ export function assignGingerly(target, source, options) {
                 continue;
             }
             // No @each in path - handle normally
+            // Check if we need to handle async methods (fire-and-forget)
+            if (withAsyncMethodsSet && pathParts.some(p => withAsyncMethodsSet.has(p))) {
+                // Fire-and-forget: dynamically import the async evaluator and run the chain
+                const capturedTarget = target;
+                const capturedPathParts = pathParts;
+                const capturedValue = value;
+                const capturedWithMethodsSet = withMethodsSet || new Set();
+                const capturedOptions = options;
+                (async () => {
+                    const { evaluatePathWithAsyncMethods } = await import('./evaluatePathWithAsyncMethods.js');
+                    const result = await evaluatePathWithAsyncMethods(capturedTarget, capturedPathParts, capturedValue, capturedWithMethodsSet, withAsyncMethodsSet);
+                    if (result.isMethod || result.isAsyncMethod) {
+                        // Last segment is a method — call it
+                        const method = result.target[result.lastKey];
+                        if (typeof method === 'function') {
+                            const returnVal = Array.isArray(capturedValue)
+                                ? method.apply(result.target, capturedValue)
+                                : method.call(result.target, capturedValue);
+                            // If it's an async method, await it (for side effects)
+                            if (result.isAsyncMethod)
+                                await returnVal;
+                        }
+                    }
+                    else {
+                        // Not a method — assign the value
+                        const lastKey = result.lastKey;
+                        const parent = result.target;
+                        if (typeof capturedValue === 'object' && capturedValue !== null && !Array.isArray(capturedValue)) {
+                            if (lastKey in parent && isReadonlyProperty(parent, lastKey)) {
+                                const currentValue = parent[lastKey];
+                                if (typeof currentValue !== 'object' || currentValue === null) {
+                                    throw new Error(`Cannot merge object into readonly primitive property '${String(lastKey)}'`);
+                                }
+                                assignGingerly(currentValue, capturedValue, capturedOptions);
+                            }
+                            else {
+                                parent[lastKey] = capturedValue;
+                            }
+                        }
+                        else {
+                            parent[lastKey] = capturedValue;
+                        }
+                    }
+                })();
+                continue;
+            }
             // Check if we need to handle methods
             if (withMethodsSet) {
                 const result = evaluatePathWithMethods(target, pathParts, value, withMethodsSet);
@@ -763,6 +844,10 @@ export function assignGingerly(target, source, options) {
                 // Not a method - proceed with normal assignment using evaluated target
                 const lastKey = result.lastKey;
                 const parent = result.target;
+                // Check for static assignTo protocol
+                if (lastKey in parent && tryAssignTo(parent[lastKey], value, parent, lastKey)) {
+                    continue;
+                }
                 if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
                     // Check if property exists and is readonly
                     if (lastKey in parent && isReadonlyProperty(parent, lastKey)) {
@@ -785,6 +870,10 @@ export function assignGingerly(target, source, options) {
                 // No withMethods - use original logic
                 const lastKey = pathParts[pathParts.length - 1];
                 const parent = ensureNestedPath(target, pathParts);
+                // Check for static assignTo protocol
+                if (lastKey in parent && tryAssignTo(parent[lastKey], value, parent, lastKey)) {
+                    continue;
+                }
                 if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
                     // Check if property exists and is readonly
                     if (lastKey in parent && isReadonlyProperty(parent, lastKey)) {
@@ -823,6 +912,10 @@ export function assignGingerly(target, source, options) {
                 continue;
             }
             // Normal assignment
+            // Check for static assignTo protocol
+            if (key in target && tryAssignTo(target[key], value, target, key)) {
+                continue;
+            }
             if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
                 // Check if property exists and is readonly
                 if (key in target && isReadonlyProperty(target, key)) {

package/assignGingerly.ts

@@ -97,6 +97,25 @@ export interface IAssignGingerlyOptions {
    * // Later: controller.abort(); // Cleanup all listeners
    */
   signal?: AbortSignal;
+
+  /**
+   * List of property names that should be treated as async methods.
+   * Works together with withMethods — async methods are awaited before
+   * continuing the chain.
+   * 
+   * The path evaluation for keys containing async methods is fire-and-forget:
+   * assignGingerly remains synchronous and returns immediately. The async
+   * chain completes in the background.
+   * 
+   * NOTE: Interaction with @each and @eachTime is not yet implemented.
+   * 
+   * Example:
+   * assignGingerly(el, {
+   *   '?.whenFeatureReady?.photoTaker?.someProp': 'hello'
+   * }, { withAsyncMethods: ['whenFeatureReady'] });
+   * // Calls: (await el.whenFeatureReady('photoTaker')).someProp = 'hello'
+   */
+  withAsyncMethods?: string[] | Set<string>;
 }
 
 /**
@@ -328,12 +347,22 @@ 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')
+/**
+ * Path cache for parsed path strings in assignGingerly.
+ * Avoids re-splitting the same path on repeated calls.
+ */
+const agPathCache = new Map<string, string[]>();
+
+/**
  * Paths must use ?. notation — plain dot notation is not supported.
  */
 function parsePath(path: string): string[] {
-  return path
-    .split('?.')
-    .filter(part => part.length > 0);
+  let parts = agPathCache.get(path);
+  if (!parts) {
+    parts = path.split('?.').filter(part => part.length > 0);
+    agPathCache.set(path, parts);
+  }
+  return parts;
 }
 
 /**
@@ -396,6 +425,27 @@ export function isReadonlyProperty(obj: any, propName: string | symbol): boolean
   return false;
 }
 
+/**
+ * Checks if a class defines a static `assignTo` method and calls it.
+ * This is the "bring your own assigner" protocol — classes can opt into
+ * custom assignment behavior by defining `static assignTo`.
+ * 
+ * Only triggers for classes that explicitly define `assignTo` on themselves
+ * (not inherited from Object or other base classes).
+ * 
+ * @returns true if assignTo was found and called, false otherwise
+ */
+function tryAssignTo(currentValue: any, value: any, parent: any, key: string | symbol): boolean {
+  if (currentValue != null && typeof currentValue === 'object') {
+    const { constructor } = currentValue;
+    if (constructor && Object.hasOwn(constructor, 'assignTo') && typeof constructor.assignTo === 'function') {
+      constructor.assignTo(currentValue, value, parent, key);
+      return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Helper function to check if a value is a class instance (not a plain object)
  * Returns true for instances of classes, false for plain objects, arrays, and primitives
@@ -654,6 +704,13 @@ export function assignGingerly(
       : new Set(options.withMethods)
     : undefined;
 
+  // Convert withAsyncMethods array to Set for O(1) lookup
+  const withAsyncMethodsSet = options?.withAsyncMethods
+    ? options.withAsyncMethods instanceof Set
+      ? options.withAsyncMethods
+      : new Set(options.withAsyncMethods)
+    : undefined;
+
   // Convert aka object to Map for O(1) lookup and validate aliases
   const aliasMap = new Map<string, string>();
   if (options?.aka) {
@@ -919,6 +976,53 @@ export function assignGingerly(
       }
       
       // No @each in path - handle normally
+      // Check if we need to handle async methods (fire-and-forget)
+      if (withAsyncMethodsSet && pathParts.some(p => withAsyncMethodsSet.has(p))) {
+        // Fire-and-forget: dynamically import the async evaluator and run the chain
+        const capturedTarget = target;
+        const capturedPathParts = pathParts;
+        const capturedValue = value;
+        const capturedWithMethodsSet = withMethodsSet || new Set<string>();
+        const capturedOptions = options;
+        (async () => {
+          const { evaluatePathWithAsyncMethods } = await import('./evaluatePathWithAsyncMethods.js');
+          const result = await evaluatePathWithAsyncMethods(
+            capturedTarget, capturedPathParts, capturedValue,
+            capturedWithMethodsSet, withAsyncMethodsSet
+          );
+
+          if (result.isMethod || result.isAsyncMethod) {
+            // Last segment is a method — call it
+            const method = result.target[result.lastKey];
+            if (typeof method === 'function') {
+              const returnVal = Array.isArray(capturedValue)
+                ? method.apply(result.target, capturedValue)
+                : method.call(result.target, capturedValue);
+              // If it's an async method, await it (for side effects)
+              if (result.isAsyncMethod) await returnVal;
+            }
+          } else {
+            // Not a method — assign the value
+            const lastKey = result.lastKey;
+            const parent = result.target;
+            if (typeof capturedValue === 'object' && capturedValue !== null && !Array.isArray(capturedValue)) {
+              if (lastKey in parent && isReadonlyProperty(parent, lastKey)) {
+                const currentValue = parent[lastKey];
+                if (typeof currentValue !== 'object' || currentValue === null) {
+                  throw new Error(`Cannot merge object into readonly primitive property '${String(lastKey)}'`);
+                }
+                assignGingerly(currentValue, capturedValue, capturedOptions);
+              } else {
+                parent[lastKey] = capturedValue;
+              }
+            } else {
+              parent[lastKey] = capturedValue;
+            }
+          }
+        })();
+        continue;
+      }
+
       // Check if we need to handle methods
       if (withMethodsSet) {
         const result = evaluatePathWithMethods(target, pathParts, value, withMethodsSet);
@@ -941,6 +1045,11 @@ export function assignGingerly(
         const lastKey = result.lastKey;
         const parent = result.target;
         
+        // Check for static assignTo protocol
+        if (lastKey in parent && tryAssignTo(parent[lastKey], value, parent, lastKey)) {
+          continue;
+        }
+
         if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
           // Check if property exists and is readonly
           if (lastKey in parent && isReadonlyProperty(parent, lastKey)) {
@@ -961,6 +1070,11 @@ export function assignGingerly(
         const lastKey = pathParts[pathParts.length - 1];
         const parent = ensureNestedPath(target, pathParts);
 
+        // Check for static assignTo protocol
+        if (lastKey in parent && tryAssignTo(parent[lastKey], value, parent, lastKey)) {
+          continue;
+        }
+
         if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
           // Check if property exists and is readonly
           if (lastKey in parent && isReadonlyProperty(parent, lastKey)) {
@@ -997,6 +1111,11 @@ export function assignGingerly(
       }
       
       // Normal assignment
+      // Check for static assignTo protocol
+      if (key in target && tryAssignTo(target[key], value, target, key)) {
+        continue;
+      }
+
       if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
         // Check if property exists and is readonly
         if (key in target && isReadonlyProperty(target, key)) {

package/evaluatePathWithAsyncMethods.js

@@ -0,0 +1,90 @@
+/**
+ * evaluatePathWithAsyncMethods - Async variant of evaluatePathWithMethods.
+ *
+ * Walks a path of property accesses and method calls, awaiting any methods
+ * that are in the withAsyncMethods set before continuing the chain.
+ *
+ * This module is loaded dynamically (only when withAsyncMethods is used)
+ * to avoid adding async overhead to the synchronous path.
+ *
+ * NOTE: Interaction with @each and @eachTime is not yet implemented.
+ * Deferred until a compelling use case presents itself.
+ */
+/**
+ * Evaluates a path with support for both sync and async method calls.
+ * Awaits the return value of any method in the withAsyncMethods set.
+ *
+ * @param target - The root object to start path evaluation from
+ * @param pathParts - Array of path segments (split from '?.' notation)
+ * @param value - The value to assign or pass as argument at the end
+ * @param withMethods - Set of method names that are called synchronously
+ * @param withAsyncMethods - Set of method names that are awaited
+ * @returns Promise resolving to the evaluation result
+ */
+export async function evaluatePathWithAsyncMethods(target, pathParts, value, withMethods, withAsyncMethods) {
+    let current = target;
+    let i = 0;
+    // Process all segments except the last one
+    while (i < pathParts.length - 1) {
+        const part = pathParts[i];
+        const nextPart = pathParts[i + 1];
+        if (withAsyncMethods.has(part)) {
+            // Async method — call and await
+            const method = current[part];
+            if (typeof method === 'function') {
+                if (withAsyncMethods.has(nextPart) || withMethods.has(nextPart)) {
+                    // Next is also a method — call current with no args
+                    current = await method.call(current);
+                }
+                else {
+                    // Call with next part as string arg, then await
+                    current = await method.call(current, nextPart);
+                    i++; // Skip next part since we consumed it as argument
+                }
+            }
+            else {
+                // Not a function — just access property
+                if (current[part] === undefined || current[part] === null) {
+                    current[part] = {};
+                }
+                current = current[part];
+            }
+        }
+        else if (withMethods.has(part)) {
+            // Sync method — same logic as evaluatePathWithMethods
+            const method = current[part];
+            if (typeof method === 'function') {
+                if (withMethods.has(nextPart) || withAsyncMethods.has(nextPart)) {
+                    // Next is also a method — call current with no args
+                    current = method.call(current);
+                }
+                else {
+                    // Call with next part as string arg
+                    current = method.call(current, nextPart);
+                    i++; // Skip next part since we consumed it as argument
+                }
+            }
+            else {
+                if (!(part in current) || typeof current[part] !== 'object' || current[part] === null) {
+                    current[part] = {};
+                }
+                current = current[part];
+            }
+        }
+        else {
+            // Not a method — normal property access
+            if (!(part in current) || typeof current[part] !== 'object' || current[part] === null) {
+                current[part] = {};
+            }
+            current = current[part];
+        }
+        i++;
+    }
+    const lastKey = pathParts[pathParts.length - 1];
+    return {
+        target: current,
+        lastKey,
+        isMethod: withMethods.has(lastKey),
+        isAsyncMethod: withAsyncMethods.has(lastKey)
+    };
+}

package/evaluatePathWithAsyncMethods.ts

@@ -0,0 +1,102 @@
+/**
+ * evaluatePathWithAsyncMethods - Async variant of evaluatePathWithMethods.
+ * 
+ * Walks a path of property accesses and method calls, awaiting any methods
+ * that are in the withAsyncMethods set before continuing the chain.
+ * 
+ * This module is loaded dynamically (only when withAsyncMethods is used)
+ * to avoid adding async overhead to the synchronous path.
+ * 
+ * NOTE: Interaction with @each and @eachTime is not yet implemented.
+ * Deferred until a compelling use case presents itself.
+ */
+
+export interface AsyncPathResult {
+    target: any;
+    lastKey: string;
+    isMethod: boolean;
+    isAsyncMethod: boolean;
+}
+
+/**
+ * Evaluates a path with support for both sync and async method calls.
+ * Awaits the return value of any method in the withAsyncMethods set.
+ * 
+ * @param target - The root object to start path evaluation from
+ * @param pathParts - Array of path segments (split from '?.' notation)
+ * @param value - The value to assign or pass as argument at the end
+ * @param withMethods - Set of method names that are called synchronously
+ * @param withAsyncMethods - Set of method names that are awaited
+ * @returns Promise resolving to the evaluation result
+ */
+export async function evaluatePathWithAsyncMethods(
+    target: any,
+    pathParts: string[],
+    value: any,
+    withMethods: Set<string>,
+    withAsyncMethods: Set<string>
+): Promise<AsyncPathResult> {
+    let current = target;
+    let i = 0;
+
+    // Process all segments except the last one
+    while (i < pathParts.length - 1) {
+        const part = pathParts[i];
+        const nextPart = pathParts[i + 1];
+
+        if (withAsyncMethods.has(part)) {
+            // Async method — call and await
+            const method = current[part];
+            if (typeof method === 'function') {
+                if (withAsyncMethods.has(nextPart) || withMethods.has(nextPart)) {
+                    // Next is also a method — call current with no args
+                    current = await method.call(current);
+                } else {
+                    // Call with next part as string arg, then await
+                    current = await method.call(current, nextPart);
+                    i++; // Skip next part since we consumed it as argument
+                }
+            } else {
+                // Not a function — just access property
+                if (current[part] === undefined || current[part] === null) {
+                    current[part] = {};
+                }
+                current = current[part];
+            }
+        } else if (withMethods.has(part)) {
+            // Sync method — same logic as evaluatePathWithMethods
+            const method = current[part];
+            if (typeof method === 'function') {
+                if (withMethods.has(nextPart) || withAsyncMethods.has(nextPart)) {
+                    // Next is also a method — call current with no args
+                    current = method.call(current);
+                } else {
+                    // Call with next part as string arg
+                    current = method.call(current, nextPart);
+                    i++; // Skip next part since we consumed it as argument
+                }
+            } else {
+                if (!(part in current) || typeof current[part] !== 'object' || current[part] === null) {
+                    current[part] = {};
+                }
+                current = current[part];
+            }
+        } else {
+            // Not a method — normal property access
+            if (!(part in current) || typeof current[part] !== 'object' || current[part] === null) {
+                current[part] = {};
+            }
+            current = current[part];
+        }
+
+        i++;
+    }
+
+    const lastKey = pathParts[pathParts.length - 1];
+    return {
+        target: current,
+        lastKey,
+        isMethod: withMethods.has(lastKey),
+        isAsyncMethod: withAsyncMethods.has(lastKey)
+    };
+}

package/index.js

@@ -7,6 +7,8 @@ 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 { resolveValues, resolveValue } from './resolveValues.js';
 export { assignFrom } from './assignFrom.js';
+export { assignFeatures, FeaturesRegistry, captureFeatureInitVals, PropertyBag } from './assignFeatures.js';
+export { installForwarding } from './installForwarding.js';
 import './object-extension.js';

package/index.ts

@@ -7,6 +7,8 @@ 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 {resolveValues, resolveValue} from './resolveValues.js';
 export {assignFrom} from './assignFrom.js';
+export {assignFeatures, FeaturesRegistry, captureFeatureInitVals, PropertyBag} from './assignFeatures.js';
+export {installForwarding} from './installForwarding.js';
 import './object-extension.js';

package/installForwarding.js

@@ -0,0 +1,61 @@
+/**
+ * installForwarding - Installs getter/setter property forwarding on a class prototype.
+ *
+ * Reads `static propLinks` from the constructor and installs getter/setter pairs
+ * that delegate to nested paths on the instance.
+ *
+ * - Getter uses `resolveValue` for full path resolution (with caching, method support, aliases).
+ * - Setter uses `assignGingerly` for path-based assignment (creates intermediates as needed).
+ *
+ * @example
+ * import { installForwarding } from 'assign-gingerly/installForwarding.js';
+ *
+ * class ClubMember extends HTMLElement {
+ *     static propLinks = {
+ *         'command': '?.behaviors?.commandBehavior?.command',
+ *         'commandForElement': '?.behaviors?.commandBehavior?.commandForElement'
+ *     };
+ * }
+ *
+ * installForwarding(ClubMember);
+ * // Now el.command delegates to el.behaviors.commandBehavior.command
+ */
+import { resolveValue } from './resolveValues.js';
+import assignGingerly from './assignGingerly.js';
+/**
+ * Installs property forwarding on a class prototype based on `static propLinks`.
+ *
+ * Each entry in `propLinks` maps a top-level property name to a `?.`-delimited
+ * path string. A getter/setter pair is installed on the prototype that:
+ * - Getter: resolves the path against `this` using `resolveValue`
+ * - Setter: assigns the value at the path using `assignGingerly`
+ *
+ * @param ctr - The constructor whose prototype will receive forwarded properties
+ * @param options - Optional assignGingerly/resolveValues options (withMethods, aka, etc.)
+ * @throws If a forwarded property name already exists on the prototype
+ */
+export function installForwarding(ctr, options) {
+    const propLinks = ctr.propLinks;
+    if (!propLinks)
+        return;
+    for (const [propName, path] of Object.entries(propLinks)) {
+        // Validate: don't overwrite existing properties
+        if (Object.getOwnPropertyDescriptor(ctr.prototype, propName)) {
+            throw new Error(`installForwarding: "${propName}" already exists on ${ctr.name || 'constructor'}.prototype`);
+        }
+        // Validate: path must start with ?.
+        if (!path.startsWith('?.')) {
+            throw new Error(`installForwarding: path for "${propName}" must start with "?." — got "${path}"`);
+        }
+        Object.defineProperty(ctr.prototype, propName, {
+            get() {
+                return resolveValue(path, this, options);
+            },
+            set(value) {
+                assignGingerly(this, { [path]: value }, options);
+            },
+            enumerable: true,
+            configurable: true
+        });
+    }
+}

package/installForwarding.ts

@@ -0,0 +1,71 @@
+/**
+ * installForwarding - Installs getter/setter property forwarding on a class prototype.
+ * 
+ * Reads `static propLinks` from the constructor and installs getter/setter pairs
+ * that delegate to nested paths on the instance.
+ * 
+ * - Getter uses `resolveValue` for full path resolution (with caching, method support, aliases).
+ * - Setter uses `assignGingerly` for path-based assignment (creates intermediates as needed).
+ * 
+ * @example
+ * import { installForwarding } from 'assign-gingerly/installForwarding.js';
+ * 
+ * class ClubMember extends HTMLElement {
+ *     static propLinks = {
+ *         'command': '?.behaviors?.commandBehavior?.command',
+ *         'commandForElement': '?.behaviors?.commandBehavior?.commandForElement'
+ *     };
+ * }
+ * 
+ * installForwarding(ClubMember);
+ * // Now el.command delegates to el.behaviors.commandBehavior.command
+ */
+
+import { resolveValue, ResolveValuesOptions } from './resolveValues.js';
+import assignGingerly, { IAssignGingerlyOptions } from './assignGingerly.js';
+
+export interface InstallForwardingOptions extends ResolveValuesOptions, IAssignGingerlyOptions {}
+
+/**
+ * Installs property forwarding on a class prototype based on `static propLinks`.
+ * 
+ * Each entry in `propLinks` maps a top-level property name to a `?.`-delimited
+ * path string. A getter/setter pair is installed on the prototype that:
+ * - Getter: resolves the path against `this` using `resolveValue`
+ * - Setter: assigns the value at the path using `assignGingerly`
+ * 
+ * @param ctr - The constructor whose prototype will receive forwarded properties
+ * @param options - Optional assignGingerly/resolveValues options (withMethods, aka, etc.)
+ * @throws If a forwarded property name already exists on the prototype
+ */
+export function installForwarding(ctr: Function, options?: InstallForwardingOptions): void {
+    const propLinks: Record<string, string> | undefined = (ctr as any).propLinks;
+    if (!propLinks) return;
+
+    for (const [propName, path] of Object.entries(propLinks)) {
+        // Validate: don't overwrite existing properties
+        if (Object.getOwnPropertyDescriptor(ctr.prototype, propName)) {
+            throw new Error(
+                `installForwarding: "${propName}" already exists on ${(ctr as any).name || 'constructor'}.prototype`
+            );
+        }
+
+        // Validate: path must start with ?.
+        if (!path.startsWith('?.')) {
+            throw new Error(
+                `installForwarding: path for "${propName}" must start with "?." — got "${path}"`
+            );
+        }
+
+        Object.defineProperty(ctr.prototype, propName, {
+            get(this: any) {
+                return resolveValue(path, this, options);
+            },
+            set(this: any, value: any) {
+                assignGingerly(this, { [path]: value }, options);
+            },
+            enumerable: true,
+            configurable: true
+        });
+    }
+}