assign-gingerly 0.0.59 → 0.0.60

package/handlers/manageTemplateList.ts

@@ -18,7 +18,7 @@
  *         },
  *         fromEachItem: {
  *             assignToFragment: { '?.querySelector?.tr?.ish': '?.' },
- *             withOptions: { withMethods: ['querySelector'], inferredAssignments: true },
+ *             withOptions: { withMethods: ['querySelector'], infer: true },
  *             resolve: { key: '?.rank' }
  *         }
  *     }
@@ -75,6 +75,7 @@ export class ManageTemplateListHandler implements AssignFromHandler {
         }
 
         const fromEachItem = this.config.fromEachItem;
+        const configs = fromEachItem?.configs; // Array form for multi-element templates
         const assignToFragment = fromEachItem?.assignToFragment ?? {};
         const withOptions = fromEachItem?.withOptions ?? {};
         const perItemResolve = fromEachItem?.resolve ?? {};
@@ -85,10 +86,10 @@ export class ManageTemplateListHandler implements AssignFromHandler {
         const sourceAssignToFragment = fromSource?.assignToFragment;
         const sourceWithOptions = fromSource?.withOptions ?? {};
 
-        // Detect fast path: no assignToFragment patterns, just inferredAssignments
-        const hasAssignPatterns = Object.keys(assignToFragment).length > 0;
-        const inferredConfig = withOptions.inferredAssignments;
-        const useFastPath = !hasAssignPatterns && inferredConfig && !sourceAssignToFragment;
+        // Detect fast path: no assignToFragment patterns, just infer (only for non-configs mode)
+        const hasAssignPatterns = !configs && Object.keys(assignToFragment).length > 0;
+        const inferredConfig = !configs && withOptions.infer;
+        const useFastPath = !configs && !hasAssignPatterns && inferredConfig && !sourceAssignToFragment;
 
         const name = markerName ?? getMarkerName(instantiate) ?? 'templateList';
 
@@ -149,17 +150,28 @@ export class ManageTemplateListHandler implements AssignFromHandler {
             if (state.keyToNodes.has(key) && oldKeys.has(key)) {
                 // Existing item — update in place
                 const existingNodes = state.keyToNodes.get(key)!;
-                const rootEl = existingNodes.find(n => n instanceof Element) as Element | undefined;
-                if (rootEl) {
-                    const shouldYield = yieldEvery && i > 0 && i % yieldEvery === 0;
-                    if (shouldYield) await new Promise(r => setTimeout(r, 0));
-                    if (processInferred) {
-                        processInferred(rootEl, item, inferredConfig === true ? { byItemprop: true } : inferredConfig);
-                    } else {
-                        assignFrom(rootEl, assignToFragment, { from: item, ...withOptions });
+                const shouldYield = yieldEvery && i > 0 && i % yieldEvery === 0;
+                if (shouldYield) await new Promise(r => setTimeout(r, 0));
+
+                if (configs) {
+                    // Multi-element: zip configs with element nodes
+                    const elements = existingNodes.filter(n => n instanceof Element) as Element[];
+                    const len = Math.min(elements.length, configs.length);
+                    for (let j = 0; j < len; j++) {
+                        const cfg = configs[j];
+                        assignFrom(elements[j], cfg.assignToFragment ?? {}, { from: item, ...cfg.withOptions });
                     }
-                    if (sourceAssignToFragment && options?.from) {
-                        assignFrom(rootEl, sourceAssignToFragment, { from: options.from, ...sourceWithOptions });
+                } else {
+                    const rootEl = existingNodes.find(n => n instanceof Element) as Element | undefined;
+                    if (rootEl) {
+                        if (processInferred) {
+                            processInferred(rootEl, item, inferredConfig === true ? { byItemprop: true } : inferredConfig);
+                        } else {
+                            assignFrom(rootEl, assignToFragment, { from: item, ...withOptions });
+                        }
+                        if (sourceAssignToFragment && options?.from) {
+                            assignFrom(rootEl, sourceAssignToFragment, { from: options.from, ...sourceWithOptions });
+                        }
                     }
                 }
                 newKeyToNodes.set(key, existingNodes);
@@ -180,21 +192,32 @@ export class ManageTemplateListHandler implements AssignFromHandler {
                 const clonedNodes = Array.from(content.childNodes);
 
                 // Apply per-item assignments to the cloned fragment
-                const rootEl = clonedNodes.find(n => n instanceof Element) as Element | undefined;
-                if (rootEl) {
-                    const tempContainer = document.createDocumentFragment();
-                    tempContainer.appendChild(content);
-
-                    const shouldYield = yieldEvery && i > 0 && i % yieldEvery === 0;
-                    if (shouldYield) await new Promise(r => setTimeout(r, 0));
-                    if (processInferred) {
-                        processInferred(rootEl, item, inferredConfig === true ? { byItemprop: true } : inferredConfig);
-                    } else {
-                        assignFrom(rootEl, assignToFragment, { from: item, ...withOptions });
+                const shouldYield = yieldEvery && i > 0 && i % yieldEvery === 0;
+                if (shouldYield) await new Promise(r => setTimeout(r, 0));
+
+                if (configs) {
+                    // Multi-element: zip configs with element nodes
+                    const elements = clonedNodes.filter(n => n instanceof Element) as Element[];
+                    const len = Math.min(elements.length, configs.length);
+                    for (let j = 0; j < len; j++) {
+                        const cfg = configs[j];
+                        assignFrom(elements[j], cfg.assignToFragment ?? {}, { from: item, ...cfg.withOptions });
                     }
+                } else {
+                    const rootEl = clonedNodes.find(n => n instanceof Element) as Element | undefined;
+                    if (rootEl) {
+                        const tempContainer = document.createDocumentFragment();
+                        tempContainer.appendChild(content);
 
-                    if (sourceAssignToFragment && options?.from) {
-                        assignFrom(rootEl, sourceAssignToFragment, { from: options.from, ...sourceWithOptions });
+                        if (processInferred) {
+                            processInferred(rootEl, item, inferredConfig === true ? { byItemprop: true } : inferredConfig);
+                        } else {
+                            assignFrom(rootEl, assignToFragment, { from: item, ...withOptions });
+                        }
+
+                        if (sourceAssignToFragment && options?.from) {
+                            assignFrom(rootEl, sourceAssignToFragment, { from: options.from, ...sourceWithOptions });
+                        }
                     }
                 }
 

package/inferencer/inferencer.js

@@ -81,38 +81,26 @@ export class Infer {
         return inferValueProperty(this.enhancedElement);
     }
     ['|'](itempropAttr, scopeBoundary = '[itemscope]') {
-        const candidates = this.enhancedElement.querySelectorAll(`[itemprop="${itempropAttr}"]`);
-        return Array.from(candidates)
-            .filter(el => withScopePerimeter(this.enhancedElement, el, scopeBoundary))
-            .map(x => new Infer(x, itempropAttr));
+        return this.#queryScoped(`[itemprop="${itempropAttr}"]`, itempropAttr, scopeBoundary);
     }
     ['@'](nameAttr, scopeBoundary) {
-        const candidates = this.enhancedElement.querySelectorAll(`[name="${nameAttr}"]`);
-        const filtered = scopeBoundary
-            ? Array.from(candidates).filter(el => withScopePerimeter(this.enhancedElement, el, scopeBoundary))
-            : Array.from(candidates);
-        return filtered.map(x => new Infer(x, nameAttr));
+        return this.#queryScoped(`[name="${nameAttr}"]`, nameAttr, scopeBoundary);
     }
     ['%'](partAttr, scopeBoundary) {
-        const candidates = this.enhancedElement.querySelectorAll(`[part~="${partAttr}"]`);
-        const filtered = scopeBoundary
-            ? Array.from(candidates).filter(el => withScopePerimeter(this.enhancedElement, el, scopeBoundary))
-            : Array.from(candidates);
-        return filtered.map(x => new Infer(x, partAttr));
+        return this.#queryScoped(`[part~="${partAttr}"]`, partAttr, scopeBoundary);
     }
     ['#'](id, scopeBoundary) {
-        const candidates = this.enhancedElement.querySelectorAll(`#${id}`);
-        const filtered = scopeBoundary
-            ? Array.from(candidates).filter(el => withScopePerimeter(this.enhancedElement, el, scopeBoundary))
-            : Array.from(candidates);
-        return filtered.map(x => new Infer(x, id));
+        return this.#queryScoped(`#${id}`, id, scopeBoundary);
     }
     ['.'](className, scopeBoundary) {
-        const candidates = this.enhancedElement.querySelectorAll(`.${className}`);
+        return this.#queryScoped(`.${className}`, className, scopeBoundary);
+    }
+    #queryScoped(selector, propName, scopeBoundary) {
+        const candidates = this.enhancedElement.querySelectorAll(selector);
         const filtered = scopeBoundary
             ? Array.from(candidates).filter(el => withScopePerimeter(this.enhancedElement, el, scopeBoundary))
             : Array.from(candidates);
-        return filtered.map(x => new Infer(x, className));
+        return filtered.map(x => new Infer(x, propName));
     }
     setDisplay(vm) {
         const val = this.#propName ? vm[this.#propName] : inferBindingProperty(this.enhancedElement);

package/inferencer/inferencer.ts

@@ -103,42 +103,31 @@ export class Infer<TValue = any, TDisplay = any> {
     }
 
     ['|'](itempropAttr: string, scopeBoundary: string = '[itemscope]'){
-        const candidates = this.enhancedElement.querySelectorAll(`[itemprop="${itempropAttr}"]`);
-        return Array.from(candidates)
-            .filter(el => withScopePerimeter(this.enhancedElement, el, scopeBoundary))
-            .map(x => new Infer(x, itempropAttr));
+        return this.#queryScoped(`[itemprop="${itempropAttr}"]`, itempropAttr, scopeBoundary);
     }
 
     ['@'](nameAttr: string, scopeBoundary?: string){
-        const candidates = this.enhancedElement.querySelectorAll(`[name="${nameAttr}"]`);
-        const filtered = scopeBoundary
-            ? Array.from(candidates).filter(el => withScopePerimeter(this.enhancedElement, el, scopeBoundary))
-            : Array.from(candidates);
-        return filtered.map(x => new Infer(x, nameAttr));
+        return this.#queryScoped(`[name="${nameAttr}"]`, nameAttr, scopeBoundary);
     }
 
     ['%'](partAttr: string, scopeBoundary?: string){
-        const candidates = this.enhancedElement.querySelectorAll(`[part~="${partAttr}"]`);
-        const filtered = scopeBoundary
-            ? Array.from(candidates).filter(el => withScopePerimeter(this.enhancedElement, el, scopeBoundary))
-            : Array.from(candidates);
-        return filtered.map(x => new Infer(x, partAttr));
+        return this.#queryScoped(`[part~="${partAttr}"]`, partAttr, scopeBoundary);
     }
 
     ['#'](id: string, scopeBoundary?: string){
-        const candidates = this.enhancedElement.querySelectorAll(`#${id}`);
-        const filtered = scopeBoundary
-            ? Array.from(candidates).filter(el => withScopePerimeter(this.enhancedElement, el, scopeBoundary))
-            : Array.from(candidates);
-        return filtered.map(x => new Infer(x, id));
+        return this.#queryScoped(`#${id}`, id, scopeBoundary);
     }
 
     ['.'](className: string, scopeBoundary?: string){
-        const candidates = this.enhancedElement.querySelectorAll(`.${className}`);
+        return this.#queryScoped(`.${className}`, className, scopeBoundary);
+    }
+
+    #queryScoped(selector: string, propName: string, scopeBoundary?: string): Infer[] {
+        const candidates = this.enhancedElement.querySelectorAll(selector);
         const filtered = scopeBoundary
             ? Array.from(candidates).filter(el => withScopePerimeter(this.enhancedElement, el, scopeBoundary))
             : Array.from(candidates);
-        return filtered.map(x => new Infer(x, className));
+        return filtered.map(x => new Infer(x, propName));
     }
 
     setDisplay(vm: any){

package/inferredAssignments.js

@@ -17,11 +17,14 @@ export function processInferredAssignments(target, from, config) {
         return;
     if (!from || typeof from !== 'object')
         return;
-    const { byItemprop } = config;
-    if (byItemprop) {
-        const keys = byItemprop === true
+    const { byItemprop, byName } = config;
+    // Resolve aliases: '|' → byItemprop, '@' → byName
+    const effectiveByItemprop = byItemprop ?? config['|'];
+    const effectiveByName = byName ?? config['@'];
+    if (effectiveByItemprop) {
+        const keys = effectiveByItemprop === true
             ? Object.keys(from)
-            : byItemprop;
+            : effectiveByItemprop;
         const infer = new Infer(target);
         for (const key of keys) {
             if (!(key in from))
@@ -35,4 +38,31 @@ export function processInferredAssignments(target, from, config) {
             }
         }
     }
+    if (effectiveByName) {
+        // Normalize config
+        let keys;
+        let scopeBoundary;
+        if (effectiveByName === true) {
+            keys = Object.keys(from);
+        }
+        else if (Array.isArray(effectiveByName)) {
+            keys = effectiveByName;
+        }
+        else {
+            // Object form: { props, outside }
+            keys = effectiveByName.props === true ? Object.keys(from) : effectiveByName.props;
+            scopeBoundary = effectiveByName.outside;
+        }
+        const infer = new Infer(target);
+        for (const key of keys) {
+            if (!(key in from))
+                continue;
+            const value = from[key];
+            // Use inferencer's ['@'] method — by name attribute, optional scope boundary
+            const matches = infer['@'](key, scopeBoundary);
+            for (const match of matches) {
+                match.value = value;
+            }
+        }
+    }
 }

package/inferredAssignments.ts

@@ -20,8 +20,23 @@ export interface InferredAssignmentsConfig {
      */
     byItemprop?: string[] | true;
 
-    // Phase II:
-    // byName?: string[] | true;
+    /** Concise alias for byItemprop */
+    '|'?: string[] | true;
+
+    /**
+     * Array of property keys to distribute by name attribute.
+     * For each key, finds [name="${key}"] elements and sets the value using
+     * the inferred property (value, checked, etc.).
+     * 
+     * Pass `true` to infer all keys from the `from` source object.
+     * 
+     * Object form enables donut-hole scoping:
+     * { props: ['firstName', 'lastName'], outside: 'fieldset' }
+     */
+    byName?: string[] | true | { props: string[] | true; outside: string };
+
+    /** Concise alias for byName */
+    '@'?: string[] | true | { props: string[] | true; outside: string };
 }
 
 /**
@@ -39,12 +54,16 @@ export function processInferredAssignments(
     if (!(target instanceof Element)) return;
     if (!from || typeof from !== 'object') return;
 
-    const { byItemprop } = config;
+    const { byItemprop, byName } = config;
 
-    if (byItemprop) {
-        const keys = byItemprop === true
+    // Resolve aliases: '|' → byItemprop, '@' → byName
+    const effectiveByItemprop = byItemprop ?? config['|'];
+    const effectiveByName = byName ?? config['@'];
+
+    if (effectiveByItemprop) {
+        const keys = effectiveByItemprop === true
             ? Object.keys(from)
-            : byItemprop;
+            : effectiveByItemprop;
 
         const infer = new Infer(target);
 
@@ -62,4 +81,35 @@ export function processInferredAssignments(
             }
         }
     }
+
+    if (effectiveByName) {
+        // Normalize config
+        let keys: string[];
+        let scopeBoundary: string | undefined;
+
+        if (effectiveByName === true) {
+            keys = Object.keys(from);
+        } else if (Array.isArray(effectiveByName)) {
+            keys = effectiveByName;
+        } else {
+            // Object form: { props, outside }
+            keys = effectiveByName.props === true ? Object.keys(from) : effectiveByName.props;
+            scopeBoundary = effectiveByName.outside;
+        }
+
+        const infer = new Infer(target);
+
+        for (const key of keys) {
+            if (!(key in from)) continue;
+
+            const value = from[key];
+
+            // Use inferencer's ['@'] method — by name attribute, optional scope boundary
+            const matches: Infer[] = infer['@'](key, scopeBoundary);
+
+            for (const match of matches) {
+                match.value = value;
+            }
+        }
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.59",
+  "version": "0.0.60",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {
@@ -150,6 +150,18 @@
       "default": "./assignFrom.js",
       "types": "./assignFrom.ts"
     },
+    "./assignFrom-extension.js": {
+      "default": "./assignFrom-extension.js",
+      "types": "./assignFrom-extension.ts"
+    },
+    "./assignFromAsync-extension.js": {
+      "default": "./assignFromAsync-extension.js",
+      "types": "./assignFromAsync-extension.ts"
+    },
+    "./builtInEmoji.js": {
+      "default": "./builtInEmoji.js",
+      "types": "./builtInEmoji.ts"
+    },
     "./assignFeatures.js": {
       "default": "./assignFeatures.js",
       "types": "./assignFeatures.ts"

package/playwright.config.ts

@@ -16,9 +16,9 @@ export default defineConfig({
   /* Fail the build on CI if you accidentally left test.only in the source code. */
   forbidOnly: !!process.env.CI,
   /* Retry on CI only */
-  retries: process.env.CI ? 2 : 0,
+  retries: process.env.CI ? 1 : 0,
   /* Opt out of parallel tests on CI. */
-  workers: process.env.CI ? 1 : undefined,
+  workers: process.env.CI ? 2 : undefined,
   /* Reporter to use. See https://playwright.dev/docs/test-reporters */
   reporter: [ ['html', { open: 'never' }] ], 
   /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
@@ -50,5 +50,6 @@ export default defineConfig({
     command: 'npm run serve',
     port: 8000,
     reuseExistingServer: !process.env.CI,
+    timeout: 30000,
   },
 });

package/processHandlerCommands.js

@@ -70,8 +70,13 @@ async function resolveFromHandlers(name, handlers, permissions) {
     if (typeof entry === 'function') {
         return entry;
     }
-    // Import path string — validate and dynamically import
+    // String value — could be a built-in alias or an import path
     if (typeof entry === 'string') {
+        // Built-in alias: redirect to built-in loader
+        if (entry.startsWith('builtIns.')) {
+            return loadBuiltIn(entry);
+        }
+        // Import path string — validate and dynamically import
         if (!permissions?.crossDomainImports && !isAllowedImportPath(entry)) {
             throw new Error(`assignFrom: handler "${name}" has an invalid import path "${entry}". ` +
                 `Only relative, absolute, or bare specifier paths are allowed (no cross-domain URLs). ` +

package/processHandlerCommands.ts

@@ -81,8 +81,14 @@ async function resolveFromHandlers(
         return entry as AssignFromHandlerConstructor;
     }
 
-    // Import path string — validate and dynamically import
+    // String value — could be a built-in alias or an import path
     if (typeof entry === 'string') {
+        // Built-in alias: redirect to built-in loader
+        if (entry.startsWith('builtIns.')) {
+            return loadBuiltIn(entry);
+        }
+
+        // Import path string — validate and dynamically import
         if (!permissions?.crossDomainImports && !isAllowedImportPath(entry)) {
             throw new Error(
                 `assignFrom: handler "${name}" has an invalid import path "${entry}". ` +

package/resolveIdRef.js

@@ -18,14 +18,15 @@ const idCacheMap = new WeakMap();
 const idCounterMap = new WeakMap();
 /**
  * Generate a unique ID within a rootNode.
- * Format: _ag0, _ag1, _ag2, ...
+ * Format: -ag:0, -ag:1, -ag:2, ...
+ * Starts with '-' and contains ':' to avoid collision with JS identifiers/globalThis properties.
  */
 function generateUniqueId(rootNode) {
     let counter = idCounterMap.get(rootNode) ?? 0;
     let id;
     // Ensure uniqueness (skip if ID already exists in the document)
     do {
-        id = `_ag${counter}`;
+        id = `-ag:${counter}`;
         counter++;
     } while (rootNode.getElementById?.(id));
     idCounterMap.set(rootNode, counter);
@@ -43,6 +44,55 @@ export function resolveIdVariable(varName, target, withIds) {
     const config = withIds[varName];
     if (config === undefined)
         return undefined;
+    // For 'at' option path-based configs (array or { path }), resolve directly from target — no ID, no caching
+    // These are target-relative and fast (~2-4ns), for when structure is guaranteed stable
+    if (Array.isArray(config)) {
+        let current = target;
+        for (const idx of config) {
+            if (!current || !current.children)
+                break;
+            current = current.children[idx];
+        }
+        return current instanceof Element ? current : undefined;
+    }
+    if (typeof config === 'object' && 'path' in config && !('qry' in config)) {
+        // Determine if this is from 'at' (no ID assignment) or 'withIds' with path (assigns ID + caches)
+        // When called from 'at', we skip ID/caching. When from 'withIds', we assign ID and cache.
+        // Distinguish by presence in the options — caller passes the merged map.
+        // For now: { path } without 'noId' → assign ID + cache (withIds behavior)
+        const rootNode = target.getRootNode?.() ?? target;
+        let current = target;
+        for (const idx of config.path) {
+            if (!current || !current.children)
+                break;
+            current = current.children[idx];
+        }
+        let el = current instanceof Element ? current : null;
+        // Validation: check if resolved element matches expected selector
+        if (config.expect) {
+            const didNotMatch = !el || !el.matches(config.expect);
+            if (didNotMatch) {
+                if (config.fallback) {
+                    el = target.querySelector?.(config.expect) ?? el;
+                }
+                // Fire-and-forget: log correction suggestion
+                const capturedConfig = config;
+                const capturedVarName = varName;
+                import('./withIdsCorrector.js').then(module => {
+                    module.logConfigCorrection(target, capturedVarName, capturedConfig);
+                }).catch(() => { });
+            }
+        }
+        if (!el)
+            return undefined;
+        // Assign ID for stability against future DOM mutations
+        let id = el.id;
+        if (!id) {
+            id = generateUniqueId(rootNode);
+            el.id = id;
+        }
+        return el;
+    }
     const rootNode = target.getRootNode?.() ?? target;
     // Get or create cache for this rootNode
     let cache = idCacheMap.get(rootNode);
@@ -50,28 +100,27 @@ export function resolveIdVariable(varName, target, withIds) {
         cache = new Map();
         idCacheMap.set(rootNode, cache);
     }
-    // Check cache first
-    const cached = cache.get(varName);
-    if (cached) {
-        const el = cached.ref.deref();
-        if (el)
-            return el;
-        // WeakRef was collected — try getElementById fallback
-        const el2 = rootNode.getElementById?.(cached.id);
-        if (el2) {
-            cache.set(varName, { id: cached.id, ref: new WeakRef(el2) });
-            return el2;
-        }
-        // Element no longer exists — fall through to re-query
-    }
     // First time or cache miss — resolve the element
     let el = null;
     if (typeof config === 'string') {
         // String form: existing ID — use getElementById directly
+        // Check cache first (getElementById lookups are cacheable — global to rootNode)
+        const cached = cache.get(varName);
+        if (cached) {
+            const cachedEl = cached.ref.deref();
+            if (cachedEl)
+                return cachedEl;
+            // WeakRef was collected — try getElementById fallback
+            const el2 = rootNode.getElementById?.(cached.id);
+            if (el2) {
+                cache.set(varName, { id: cached.id, ref: new WeakRef(el2) });
+                return el2;
+            }
+        }
         el = rootNode.getElementById?.(config) ?? null;
     }
     else {
-        // Object form: { qry } — run querySelector against target
+        // Object form: { qry } — run querySelector against target (target-relative, no cache)
         el = target.querySelector?.(config.qry) ?? null;
     }
     if (!el)
@@ -82,8 +131,10 @@ export function resolveIdVariable(varName, target, withIds) {
         id = generateUniqueId(rootNode);
         el.id = id;
     }
-    // Cache it
-    cache.set(varName, { id, ref: new WeakRef(el) });
+    // Cache only for string-form (getElementById) — not for qry form (target-relative)
+    if (typeof config === 'string') {
+        cache.set(varName, { id, ref: new WeakRef(el) });
+    }
     return el;
 }
 /**