assign-gingerly 0.0.59 → 0.0.61

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/handlers/rangeSelector.js

@@ -0,0 +1,52 @@
+/**
+ * builtIns.rangeSelector handler for assignFrom.
+ * 
+ * Evaluates a value against a series of range conditions and merges
+ * the matched case's properties into the target.
+ */
+
+import assignGingerly from '../assignGingerly.js';
+
+const OPERATORS = new Set(['<=', '<', '>=', '>', '===', '!==']);
+
+function checkCondition(value, op, threshold) {
+    switch (op) {
+        case '<=': return value <= threshold;
+        case '<': return value < threshold;
+        case '>=': return value >= threshold;
+        case '>': return value > threshold;
+        case '===': return value === threshold;
+        case '!==': return value !== threshold;
+        default: return false;
+    }
+}
+
+function caseMatches(value, caseObj) {
+    for (const key of Object.keys(caseObj)) {
+        if (OPERATORS.has(key)) {
+            if (!checkCondition(value, key, caseObj[key])) {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+
+export class RangeSelectorHandler {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async assign(lhsTarget, resolvedParams) {
+        const { value, when } = resolvedParams;
+        if (!Array.isArray(when)) return;
+        for (const caseObj of when) {
+            if (caseMatches(value, caseObj)) {
+                if (caseObj.merge && typeof caseObj.merge === 'object') {
+                    assignGingerly(lhsTarget, caseObj.merge);
+                }
+                return;
+            }
+        }
+    }
+}

package/handlers/rangeSelector.ts

@@ -0,0 +1,90 @@
+/**
+ * builtIns.rangeSelector handler for assignFrom.
+ * 
+ * Evaluates a value against a series of range conditions and merges
+ * the matched case's properties into the target. Useful for converting
+ * imperative if/else-if chains into declarative JSON configs.
+ * 
+ * @example
+ * assignFrom(element, {
+ *     '?. =>': {
+ *         do: 'builtIns.rangeSelector',
+ *         get: {
+ *             value: '?.count',
+ *             when: [
+ *                 { '<=': 10, merge: { status: 'low' } },
+ *                 { '<': 20, merge: { status: 'medium' } },
+ *                 { merge: { status: 'high' } }
+ *             ]
+ *         }
+ *     }
+ * }, { from: vm });
+ */
+
+import type { AssignFromHandler } from '../assignFromAsync.js';
+import assignGingerly from '../assignGingerly.js';
+
+/**
+ * Operator keys recognized in case objects.
+ */
+const OPERATORS = new Set(['<=', '<', '>=', '>', '===', '!==']);
+
+/**
+ * Check if a single operator condition is satisfied.
+ */
+function checkCondition(value: any, op: string, threshold: any): boolean {
+    switch (op) {
+        case '<=': return value <= threshold;
+        case '<': return value < threshold;
+        case '>=': return value >= threshold;
+        case '>': return value > threshold;
+        case '===': return value === threshold;
+        case '!==': return value !== threshold;
+        default: return false;
+    }
+}
+
+/**
+ * Check if all operator conditions in a case object are satisfied (AND logic).
+ * Returns true if no operator keys present (catch-all/default case).
+ */
+function caseMatches(value: any, caseObj: Record<string, any>): boolean {
+    let hasCondition = false;
+    for (const key of Object.keys(caseObj)) {
+        if (OPERATORS.has(key)) {
+            hasCondition = true;
+            if (!checkCondition(value, key, caseObj[key])) {
+                return false;
+            }
+        }
+    }
+    // No operator keys = default/catch-all
+    return true;
+}
+
+/**
+ * RangeSelectorHandler — declarative range-based conditional merge.
+ */
+export class RangeSelectorHandler implements AssignFromHandler {
+    config: any;
+
+    constructor(config: any) {
+        this.config = config;
+    }
+
+    async assign(lhsTarget: any, resolvedParams: any): Promise<void> {
+        const { value, when } = resolvedParams;
+
+        if (!Array.isArray(when)) return;
+
+        // Find first matching case (short-circuit)
+        for (const caseObj of when) {
+            if (caseMatches(value, caseObj)) {
+                if (caseObj.merge && typeof caseObj.merge === 'object') {
+                    assignGingerly(lhsTarget, caseObj.merge);
+                }
+                return; // First match wins
+            }
+        }
+    }
+}

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.61",
   "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

@@ -17,6 +17,7 @@ const BUILT_IN_MAP = {
     'builtIns.join': './handlers/join.js',
     'builtIns.microDataJoin': './handlers/microDataJoin.js',
     'builtIns.manageTemplateList': './handlers/manageTemplateList.js',
+    'builtIns.rangeSelector': './handlers/rangeSelector.js',
 };
 /**
  * Find a handler class in a dynamically imported module.
@@ -70,8 +71,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

@@ -21,6 +21,7 @@ const BUILT_IN_MAP: Record<string, string> = {
     'builtIns.join': './handlers/join.js',
     'builtIns.microDataJoin': './handlers/microDataJoin.js',
     'builtIns.manageTemplateList': './handlers/manageTemplateList.js',
+    'builtIns.rangeSelector': './handlers/rangeSelector.js',
 };
 
 /**
@@ -81,8 +82,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}". ` +