assign-gingerly 0.0.59 → 0.0.60

package/assignFrom.js

@@ -8,7 +8,7 @@
  *
  * Handler commands (` =>`) are fire-and-forget (kicked off asynchronously, not awaited).
  */
-import { getValues } from './getValues.js';
+import { getValues, getValue } from './getValues.js';
 import assignGingerly from './assignGingerly.js';
 import { resolveIdVariable, parseIdRef } from './resolveIdRef.js';
 import { processInferredAssignments } from './inferredAssignments.js';
@@ -26,6 +26,120 @@ export const SUBSTITUTION_VARS = [
 export function isHandlerCommand(key) {
     return key.endsWith(' =>');
 }
+/**
+ * Check if a key ends with the ternary operator ' ?='.
+ */
+export function isTernaryCommand(key) {
+    return key.endsWith(' ?=');
+}
+/**
+ * Parse a ?= ternary command and extract the LHS path.
+ */
+export function parseTernaryCommand(key) {
+    if (!isTernaryCommand(key))
+        return null;
+    return key.substring(0, key.length - 3); // Remove ' ?=' suffix
+}
+/**
+ * Resolve a single value — if it's a `?.` path string, resolve against source.
+ * If it's a protocol string, resolve via protocol. Otherwise pass through as literal.
+ */
+function resolveTernaryValue(value, source, options) {
+    if (typeof value === 'string' && value.startsWith('?.')) {
+        return getValue(value, source, {
+            withMethods: options.withMethods,
+            aka: options.aka,
+            protocols: options.protocols
+        });
+    }
+    if (typeof value === 'string' && value.includes('://') && options.protocols) {
+        // Check if it matches a known protocol
+        const protoEnd = value.indexOf('://');
+        const protocol = value.substring(0, protoEnd);
+        if (options.protocols[protocol]) {
+            return getValue(value, source, {
+                withMethods: options.withMethods,
+                aka: options.aka,
+                protocols: options.protocols
+            });
+        }
+    }
+    return value;
+}
+/**
+ * Evaluate a ?= ternary expression.
+ *
+ * Supported forms:
+ * - [ifTruthy, thenResult]                         — guard (skip if falsy)
+ * - [ifTruthy, thenResult, elseResult]             — ternary
+ * - [ifTrue, trueResult, falseResult, neither]     — three-state (true/false/nullish)
+ * - [[lhs, rhs], ifEqual, ifNotEqual?]             — equality comparison
+ * - [[lhs, rhs], ifEqual]                          — equality guard
+ *
+ * Returns undefined to signal "skip assignment" (guard forms when condition not met).
+ */
+const TERNARY_SKIP = Symbol('ternary-skip');
+function evaluateTernary(arr, source, options) {
+    const condition = arr[0];
+    if (Array.isArray(condition)) {
+        // Comparison mode: [[lhs, rhs], ...] or [[lhs, op, rhs], ...]
+        const lhs = resolveTernaryValue(condition[0], source, options);
+        if (condition.length === 2) {
+            // Equality: [[lhs, rhs], result, elseResult?]
+            const rhs = resolveTernaryValue(condition[1], source, options);
+            if (lhs === rhs) {
+                return resolveTernaryValue(arr[1], source, options);
+            }
+            else {
+                return arr.length > 2 ? resolveTernaryValue(arr[2], source, options) : TERNARY_SKIP;
+            }
+        }
+        else {
+            // Operator: [[lhs, op, rhs], result, elseResult?]
+            const op = condition[1];
+            const rhs = resolveTernaryValue(condition[2], source, options);
+            const satisfied = compareWithOp(lhs, op, rhs);
+            if (satisfied) {
+                return resolveTernaryValue(arr[1], source, options);
+            }
+            else {
+                return arr.length > 2 ? resolveTernaryValue(arr[2], source, options) : TERNARY_SKIP;
+            }
+        }
+    }
+    else {
+        // Truthiness mode
+        const resolved = resolveTernaryValue(condition, source, options);
+        if (arr.length === 4) {
+            // [ifTrue, trueResult, falseResult, neitherResult]
+            if (resolved == null)
+                return resolveTernaryValue(arr[3], source, options);
+            return resolved ? resolveTernaryValue(arr[1], source, options) : resolveTernaryValue(arr[2], source, options);
+        }
+        else if (arr.length === 3) {
+            // [ifTruthy, thenResult, elseResult]
+            return resolved ? resolveTernaryValue(arr[1], source, options) : resolveTernaryValue(arr[2], source, options);
+        }
+        else {
+            // [ifTruthy, thenResult] — guard, skip if falsy
+            return resolved ? resolveTernaryValue(arr[1], source, options) : TERNARY_SKIP;
+        }
+    }
+}
+/**
+ * Compare two values with a given operator.
+ */
+function compareWithOp(lhs, op, rhs) {
+    switch (op) {
+        case '===': return lhs === rhs;
+        case '!==': return lhs !== rhs;
+        case '>': return lhs > rhs;
+        case '>=': return lhs >= rhs;
+        case '<': return lhs < rhs;
+        case '<=': return lhs <= rhs;
+        default: return lhs === rhs; // fallback to equality
+    }
+}
 /**
  * Recursively substitute a placeholder in all string values of an object.
  */
@@ -150,6 +264,7 @@ export function categorizeKeys(expandedPattern) {
     const normalPattern = {};
     const idRefNormalKeys = [];
     const idRefHandlerKeys = [];
+    const ternaryKeys = [];
     for (const key of Object.keys(expandedPattern)) {
         if (isHandlerCommand(key)) {
             if (key.startsWith('#[')) {
@@ -159,6 +274,9 @@ export function categorizeKeys(expandedPattern) {
                 handlerKeys.push(key);
             }
         }
+        else if (isTernaryCommand(key)) {
+            ternaryKeys.push(key);
+        }
         else if (key.startsWith('#[')) {
             idRefNormalKeys.push(key);
         }
@@ -166,19 +284,32 @@ export function categorizeKeys(expandedPattern) {
             normalPattern[key] = expandedPattern[key];
         }
     }
-    return { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys };
+    return { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys };
+}
+/**
+ * Merge withIds and at into a single lookup map for resolveIdVariable.
+ */
+function getEffectiveIds(options) {
+    if (!options.withIds && !options.at)
+        return undefined;
+    if (options.withIds && !options.at)
+        return options.withIds;
+    if (!options.withIds && options.at)
+        return options.at;
+    return { ...options.withIds, ...options.at };
 }
 /**
  * Process #[x] normal keys synchronously.
  */
 function processIdRefNormalKeys(idRefNormalKeys, expandedPattern, target, options) {
-    if (!options.withIds)
+    const ids = getEffectiveIds(options);
+    if (!ids)
         return;
     for (const key of idRefNormalKeys) {
         const parsed = parseIdRef(key);
         if (!parsed)
             continue;
-        const el = resolveIdVariable(parsed.varName, target, options.withIds);
+        const el = resolveIdVariable(parsed.varName, target, ids);
         if (!el)
             continue;
         const value = expandedPattern[key];
@@ -210,9 +341,55 @@ export function assignFrom(target, pattern, options, permissions) {
     // Expand looped substitution variables
     const expandedPattern = expandSubstitutions(pattern, options);
     // Categorize keys
-    const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys } = categorizeKeys(expandedPattern);
+    const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys } = categorizeKeys(expandedPattern);
+    // Process ?= ternary keys (sync)
+    if (ternaryKeys.length > 0) {
+        const ternaryResolved = {};
+        for (const key of ternaryKeys) {
+            const lhsPath = parseTernaryCommand(key);
+            if (!lhsPath)
+                continue;
+            const arr = expandedPattern[key];
+            if (!Array.isArray(arr) || arr.length < 2)
+                continue;
+            const result = evaluateTernary(arr, options.from, options);
+            if (result !== TERNARY_SKIP) {
+                ternaryResolved[lhsPath] = result;
+            }
+        }
+        if (Object.keys(ternaryResolved).length > 0) {
+            assignGingerly(target, ternaryResolved, options);
+        }
+    }
     // Process normal keys via getValues (sync) + assignGingerly
     if (Object.keys(normalPattern).length > 0) {
+        // Resolve #[x] references on RHS values before getValues
+        if (options.withIds || options.at) {
+            const ids = getEffectiveIds(options);
+            for (const key of Object.keys(normalPattern)) {
+                const value = normalPattern[key];
+                if (typeof value === 'string' && value.startsWith('#[')) {
+                    const closeIdx = value.indexOf(']');
+                    if (closeIdx !== -1) {
+                        const varName = value.substring(2, closeIdx);
+                        const el = resolveIdVariable(varName, target, ids);
+                        if (el) {
+                            const remainingPath = value.substring(closeIdx + 1);
+                            if (remainingPath) {
+                                normalPattern[key] = getValue(remainingPath, el, {
+                                    withMethods: options.withMethods,
+                                    aka: options.aka,
+                                    protocols: options.protocols
+                                });
+                            }
+                            else {
+                                normalPattern[key] = el.id; // bare #[x] → ID string
+                            }
+                        }
+                    }
+                }
+            }
+        }
         const resolved = getValues(normalPattern, options.from, {
             withMethods: options.withMethods,
             aka: options.aka,
@@ -232,13 +409,14 @@ export function assignFrom(target, pattern, options, permissions) {
         });
     }
     // Process #[x] handler keys — fire-and-forget (async)
-    if (idRefHandlerKeys.length > 0 && options.withIds) {
+    if (idRefHandlerKeys.length > 0 && (options.withIds || options.at)) {
+        const ids = getEffectiveIds(options);
         import('./processHandlerCommands.js').then(({ processHandlerCommands }) => {
             for (const key of idRefHandlerKeys) {
                 const parsed = parseIdRef(key);
                 if (!parsed)
                     continue;
-                const el = resolveIdVariable(parsed.varName, target, options.withIds);
+                const el = resolveIdVariable(parsed.varName, target, ids);
                 if (!el)
                     continue;
                 const syntheticKey = parsed.remainingPath ? `${parsed.remainingPath} =>` : ' =>';
@@ -248,15 +426,15 @@ export function assignFrom(target, pattern, options, permissions) {
         });
     }
     // Process inferred assignments (sync)
-    if (options.inferredAssignments) {
-        processInferredAssignments(target, options.from, options.inferredAssignments);
+    if (options.infer) {
+        processInferredAssignments(target, options.from, options.infer);
         // beVigilant — fire-and-forget (async)
-        if (options.inferredAssignments.beVigilant) {
+        if (options.infer.beVigilant) {
             if (!options.signal) {
-                throw new Error('assignFrom: inferredAssignments.beVigilant requires options.signal (AbortSignal) for cleanup');
+                throw new Error('assignFrom: infer.beVigilant requires options.signal (AbortSignal) for cleanup');
             }
             import('./beVigilant.js').then(({ setupVigilantObserver }) => {
-                setupVigilantObserver(target, options.from, options.inferredAssignments, options.signal);
+                setupVigilantObserver(target, options.from, options.infer, options.signal);
             });
         }
     }

package/assignFrom.ts

@@ -35,6 +35,119 @@ export function isHandlerCommand(key: string): boolean {
     return key.endsWith(' =>');
 }
 
+/**
+ * Check if a key ends with the ternary operator ' ?='.
+ */
+export function isTernaryCommand(key: string): boolean {
+    return key.endsWith(' ?=');
+}
+
+/**
+ * Parse a ?= ternary command and extract the LHS path.
+ */
+export function parseTernaryCommand(key: string): string | null {
+    if (!isTernaryCommand(key)) return null;
+    return key.substring(0, key.length - 3); // Remove ' ?=' suffix
+}
+
+/**
+ * Resolve a single value — if it's a `?.` path string, resolve against source.
+ * If it's a protocol string, resolve via protocol. Otherwise pass through as literal.
+ */
+function resolveTernaryValue(value: any, source: any, options: AssignFromOptions): any {
+    if (typeof value === 'string' && value.startsWith('?.')) {
+        return getValue(value, source, {
+            withMethods: options.withMethods,
+            aka: options.aka,
+            protocols: options.protocols
+        });
+    }
+    if (typeof value === 'string' && value.includes('://') && options.protocols) {
+        // Check if it matches a known protocol
+        const protoEnd = value.indexOf('://');
+        const protocol = value.substring(0, protoEnd);
+        if (options.protocols[protocol]) {
+            return getValue(value, source, {
+                withMethods: options.withMethods,
+                aka: options.aka,
+                protocols: options.protocols
+            });
+        }
+    }
+    return value;
+}
+
+/**
+ * Evaluate a ?= ternary expression.
+ * 
+ * Supported forms:
+ * - [ifTruthy, thenResult]                         — guard (skip if falsy)
+ * - [ifTruthy, thenResult, elseResult]             — ternary
+ * - [ifTrue, trueResult, falseResult, neither]     — three-state (true/false/nullish)
+ * - [[lhs, rhs], ifEqual, ifNotEqual?]             — equality comparison
+ * - [[lhs, rhs], ifEqual]                          — equality guard
+ * 
+ * Returns undefined to signal "skip assignment" (guard forms when condition not met).
+ */
+const TERNARY_SKIP = Symbol('ternary-skip');
+
+function evaluateTernary(arr: any[], source: any, options: AssignFromOptions): any {
+    const condition = arr[0];
+
+    if (Array.isArray(condition)) {
+        // Comparison mode: [[lhs, rhs], ...] or [[lhs, op, rhs], ...]
+        const lhs = resolveTernaryValue(condition[0], source, options);
+        if (condition.length === 2) {
+            // Equality: [[lhs, rhs], result, elseResult?]
+            const rhs = resolveTernaryValue(condition[1], source, options);
+            if (lhs === rhs) {
+                return resolveTernaryValue(arr[1], source, options);
+            } else {
+                return arr.length > 2 ? resolveTernaryValue(arr[2], source, options) : TERNARY_SKIP;
+            }
+        } else {
+            // Operator: [[lhs, op, rhs], result, elseResult?]
+            const op = condition[1] as string;
+            const rhs = resolveTernaryValue(condition[2], source, options);
+            const satisfied = compareWithOp(lhs, op, rhs);
+            if (satisfied) {
+                return resolveTernaryValue(arr[1], source, options);
+            } else {
+                return arr.length > 2 ? resolveTernaryValue(arr[2], source, options) : TERNARY_SKIP;
+            }
+        }
+    } else {
+        // Truthiness mode
+        const resolved = resolveTernaryValue(condition, source, options);
+        if (arr.length === 4) {
+            // [ifTrue, trueResult, falseResult, neitherResult]
+            if (resolved == null) return resolveTernaryValue(arr[3], source, options);
+            return resolved ? resolveTernaryValue(arr[1], source, options) : resolveTernaryValue(arr[2], source, options);
+        } else if (arr.length === 3) {
+            // [ifTruthy, thenResult, elseResult]
+            return resolved ? resolveTernaryValue(arr[1], source, options) : resolveTernaryValue(arr[2], source, options);
+        } else {
+            // [ifTruthy, thenResult] — guard, skip if falsy
+            return resolved ? resolveTernaryValue(arr[1], source, options) : TERNARY_SKIP;
+        }
+    }
+}
+
+/**
+ * Compare two values with a given operator.
+ */
+function compareWithOp(lhs: any, op: string, rhs: any): boolean {
+    switch (op) {
+        case '===': return lhs === rhs;
+        case '!==': return lhs !== rhs;
+        case '>': return lhs > rhs;
+        case '>=': return lhs >= rhs;
+        case '<': return lhs < rhs;
+        case '<=': return lhs <= rhs;
+        default: return lhs === rhs; // fallback to equality
+    }
+}
+
 /**
  * Recursively substitute a placeholder in all string values of an object.
  */
@@ -164,6 +277,7 @@ export function categorizeKeys(expandedPattern: Record<string, any>) {
   const normalPattern: Record<string, any> = {};
   const idRefNormalKeys: string[] = [];
   const idRefHandlerKeys: string[] = [];
+  const ternaryKeys: string[] = [];
 
   for (const key of Object.keys(expandedPattern)) {
     if (isHandlerCommand(key)) {
@@ -172,6 +286,8 @@ export function categorizeKeys(expandedPattern: Record<string, any>) {
       } else {
         handlerKeys.push(key);
       }
+    } else if (isTernaryCommand(key)) {
+      ternaryKeys.push(key);
     } else if (key.startsWith('#[')) {
       idRefNormalKeys.push(key);
     } else {
@@ -179,7 +295,17 @@ export function categorizeKeys(expandedPattern: Record<string, any>) {
     }
   }
 
-  return { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys };
+  return { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys };
+}
+
+/**
+ * Merge withIds and at into a single lookup map for resolveIdVariable.
+ */
+function getEffectiveIds(options: AssignFromOptions): Record<string, any> | undefined {
+  if (!options.withIds && !options.at) return undefined;
+  if (options.withIds && !options.at) return options.withIds;
+  if (!options.withIds && options.at) return options.at;
+  return { ...options.withIds, ...options.at };
 }
 
 /**
@@ -191,13 +317,14 @@ function processIdRefNormalKeys(
   target: any,
   options: AssignFromOptions
 ): void {
-  if (!options.withIds) return;
+  const ids = getEffectiveIds(options);
+  if (!ids) return;
 
   for (const key of idRefNormalKeys) {
     const parsed = parseIdRef(key);
     if (!parsed) continue;
 
-    const el = resolveIdVariable(parsed.varName, target, options.withIds);
+    const el = resolveIdVariable(parsed.varName, target, ids);
     if (!el) continue;
 
     const value = expandedPattern[key];
@@ -242,10 +369,55 @@ export function assignFrom(
   const expandedPattern = expandSubstitutions(pattern, options);
 
   // Categorize keys
-  const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys } = categorizeKeys(expandedPattern);
+  const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys } = categorizeKeys(expandedPattern);
+
+  // Process ?= ternary keys (sync)
+  if (ternaryKeys.length > 0) {
+    const ternaryResolved: Record<string, any> = {};
+    for (const key of ternaryKeys) {
+      const lhsPath = parseTernaryCommand(key);
+      if (!lhsPath) continue;
+      const arr = expandedPattern[key];
+      if (!Array.isArray(arr) || arr.length < 2) continue;
+      const result = evaluateTernary(arr, options.from, options);
+      if (result !== TERNARY_SKIP) {
+        ternaryResolved[lhsPath] = result;
+      }
+    }
+    if (Object.keys(ternaryResolved).length > 0) {
+      assignGingerly(target, ternaryResolved, options);
+    }
+  }
 
   // Process normal keys via getValues (sync) + assignGingerly
   if (Object.keys(normalPattern).length > 0) {
+    // Resolve #[x] references on RHS values before getValues
+    if (options.withIds || options.at) {
+      const ids = getEffectiveIds(options)!;
+      for (const key of Object.keys(normalPattern)) {
+        const value = normalPattern[key];
+        if (typeof value === 'string' && value.startsWith('#[')) {
+          const closeIdx = value.indexOf(']');
+          if (closeIdx !== -1) {
+            const varName = value.substring(2, closeIdx);
+            const el = resolveIdVariable(varName, target, ids);
+            if (el) {
+              const remainingPath = value.substring(closeIdx + 1);
+              if (remainingPath) {
+                normalPattern[key] = getValue(remainingPath, el, {
+                  withMethods: options.withMethods,
+                  aka: options.aka,
+                  protocols: options.protocols
+                });
+              } else {
+                normalPattern[key] = el.id; // bare #[x] → ID string
+              }
+            }
+          }
+        }
+      }
+    }
+
     const resolved = getValues(normalPattern, options.from, {
       withMethods: options.withMethods,
       aka: options.aka,
@@ -269,12 +441,13 @@ export function assignFrom(
   }
 
   // Process #[x] handler keys — fire-and-forget (async)
-  if (idRefHandlerKeys.length > 0 && options.withIds) {
+  if (idRefHandlerKeys.length > 0 && (options.withIds || options.at)) {
+    const ids = getEffectiveIds(options)!;
     import('./processHandlerCommands.js').then(({ processHandlerCommands }) => {
       for (const key of idRefHandlerKeys) {
         const parsed = parseIdRef(key);
         if (!parsed) continue;
-        const el = resolveIdVariable(parsed.varName, target, options.withIds!);
+        const el = resolveIdVariable(parsed.varName, target, ids);
         if (!el) continue;
         const syntheticKey = parsed.remainingPath ? `${parsed.remainingPath} =>` : ' =>';
         const syntheticPattern = { [syntheticKey]: expandedPattern[key] };
@@ -284,16 +457,16 @@ export function assignFrom(
   }
 
   // Process inferred assignments (sync)
-  if (options.inferredAssignments) {
-    processInferredAssignments(target, options.from, options.inferredAssignments);
+  if (options.infer) {
+    processInferredAssignments(target, options.from, options.infer);
 
     // beVigilant — fire-and-forget (async)
-    if (options.inferredAssignments.beVigilant) {
+    if (options.infer.beVigilant) {
       if (!options.signal) {
-        throw new Error('assignFrom: inferredAssignments.beVigilant requires options.signal (AbortSignal) for cleanup');
+        throw new Error('assignFrom: infer.beVigilant requires options.signal (AbortSignal) for cleanup');
       }
       import('./beVigilant.js').then(({ setupVigilantObserver }) => {
-        setupVigilantObserver(target, options.from, options.inferredAssignments!, options.signal!);
+        setupVigilantObserver(target, options.from, options.infer!, options.signal!);
       });
     }
   }

package/assignFromAsync-extension.js

@@ -0,0 +1,28 @@
+/**
+ * assignFromAsync-extension.js — Adds assignFromAsync to Object.prototype.
+ * 
+ * Import this module for the side effect of extending all objects with
+ * the assignFromAsync method, enabling awaitable handler execution:
+ * 
+ * @example
+ * import 'assign-gingerly/assignFromAsync-extension.js';
+ * 
+ * await oElement.assignFromAsync({
+ *     '?.querySelector?..mainView =>': {
+ *         do: 'builtIns.lazyLoad',
+ *         get: { if: '?.isVisible', instantiate: 'globalThis://myTemplate' }
+ *     }
+ * }, { from: vm, withMethods: ['querySelector'], protocols: { globalThis: k => globalThis[k] } });
+ */
+
+import { assignFromAsync } from './assignFromAsync.js';
+
+Object.defineProperty(Object.prototype, 'assignFromAsync', {
+  value: async function (pattern, options) {
+    await assignFromAsync(this, pattern, options);
+    return this;
+  },
+  writable: true,
+  enumerable: false,
+  configurable: true,
+});

package/assignFromAsync-extension.ts

@@ -0,0 +1,58 @@
+/**
+ * assignFromAsync-extension.ts — Adds assignFromAsync to Object.prototype.
+ * 
+ * Import this module for the side effect of extending all objects with
+ * the assignFromAsync method, enabling awaitable handler execution:
+ * 
+ * @example
+ * import 'assign-gingerly/assignFromAsync-extension.js';
+ * 
+ * await oElement.assignFromAsync({
+ *     '?.querySelector?..mainView =>': {
+ *         do: 'builtIns.lazyLoad',
+ *         get: { if: '?.isVisible', instantiate: 'globalThis://myTemplate' }
+ *     }
+ * }, { from: vm, withMethods: ['querySelector'], protocols: { globalThis: k => globalThis[k] } });
+ */
+
+import { assignFromAsync } from './assignFromAsync.js';
+import type { AssignFromOptions } from './assignFromAsync.js';
+
+declare global {
+  interface Object {
+    /**
+     * Resolve RHS path strings from a source object and assign into this object.
+     * Async — awaits handler execution and supports async protocol handlers.
+     * 
+     * @param pattern - Object with LHS paths as keys and RHS path strings (or literals) as values
+     * @param options - Configuration including `from` (source object), protocols, withMethods, etc.
+     * @returns Promise resolving to this object after assignment
+     * 
+     * @example
+     * await oElement.assignFromAsync({
+     *     '?.querySelector?..outlet =>': {
+     *         do: 'builtIns.lazyLoad',
+     *         get: { if: '?.showContent', instantiate: 'globalThis://myTemplate' }
+     *     }
+     * }, { from: viewModel, withMethods: ['querySelector'], protocols: { globalThis: k => globalThis[k] } });
+     */
+    assignFromAsync(
+      pattern: Record<string, any>,
+      options: AssignFromOptions
+    ): Promise<this>;
+  }
+}
+
+Object.defineProperty(Object.prototype, 'assignFromAsync', {
+  value: async function <T extends object>(
+    this: T,
+    pattern: Record<string, any>,
+    options: AssignFromOptions
+  ): Promise<T> {
+    await assignFromAsync(this, pattern, options);
+    return this;
+  },
+  writable: true,
+  enumerable: false,
+  configurable: true,
+});

package/assignFromAsync.js

@@ -41,13 +41,14 @@ export async function assignFromAsync(target, pattern, options, permissions) {
         assignGingerly(target, resolved, options);
     }
     // Process #[x] normal keys — resolve element, then apply remaining path + value
-    if (idRefNormalKeys.length > 0 && options.withIds) {
+    if (idRefNormalKeys.length > 0 && (options.withIds || options.at)) {
+        const ids = { ...options.withIds, ...options.at };
         const { resolveIdVariable, parseIdRef } = await import('./resolveIdRef.js');
         for (const key of idRefNormalKeys) {
             const parsed = parseIdRef(key);
             if (!parsed)
                 continue;
-            const el = resolveIdVariable(parsed.varName, target, options.withIds);
+            const el = resolveIdVariable(parsed.varName, target, ids);
             if (!el)
                 continue;
             const value = expandedPattern[key];
@@ -75,14 +76,15 @@ export async function assignFromAsync(target, pattern, options, permissions) {
         await _processHandlerCommands(target, handlerKeys, expandedPattern, options, permissions);
     }
     // Process #[x] handler keys — resolve element, then pass to handler processing
-    if (idRefHandlerKeys.length > 0 && options.withIds) {
+    if (idRefHandlerKeys.length > 0 && (options.withIds || options.at)) {
+        const ids = { ...options.withIds, ...options.at };
         const { resolveIdVariable, parseIdRef } = await import('./resolveIdRef.js');
         _processHandlerCommands ??= (await import('./processHandlerCommands.js')).processHandlerCommands;
         for (const key of idRefHandlerKeys) {
             const parsed = parseIdRef(key);
             if (!parsed)
                 continue;
-            const el = resolveIdVariable(parsed.varName, target, options.withIds);
+            const el = resolveIdVariable(parsed.varName, target, ids);
             if (!el)
                 continue;
             // Build a synthetic key for processHandlerCommands:
@@ -97,16 +99,16 @@ export async function assignFromAsync(target, pattern, options, permissions) {
         }
     }
     // Process inferred assignments — dynamically imported only when option is present
-    if (options.inferredAssignments) {
+    if (options.infer) {
         const { processInferredAssignments } = await import('./inferredAssignments.js');
-        await processInferredAssignments(target, options.from, options.inferredAssignments);
+        await processInferredAssignments(target, options.from, options.infer);
         // Set up MutationObserver for new matching elements if beVigilant
-        if (options.inferredAssignments.beVigilant) {
+        if (options.infer.beVigilant) {
             if (!options.signal) {
-                throw new Error('assignFrom: inferredAssignments.beVigilant requires options.signal (AbortSignal) for cleanup');
+                throw new Error('assignFrom: infer.beVigilant requires options.signal (AbortSignal) for cleanup');
             }
             const { setupVigilantObserver } = await import('./beVigilant.js');
-            setupVigilantObserver(target, options.from, options.inferredAssignments, options.signal);
+            setupVigilantObserver(target, options.from, options.infer, options.signal);
         }
     }
     // Process bulk enhancements — dynamically imported only when option is present