assign-gingerly 0.0.58 → 0.0.60

package/inferredAssignments.js

@@ -12,16 +12,19 @@ import { Infer } from './inferencer/inferencer.js';
  * @param from - The source object containing values to distribute
  * @param config - The inferredAssignments configuration
  */
-export async function processInferredAssignments(target, from, config) {
+export function processInferredAssignments(target, from, config) {
     if (!(target instanceof Element))
         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 async 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 };
 }
 
 /**
@@ -31,20 +46,24 @@ export interface InferredAssignmentsConfig {
  * @param from - The source object containing values to distribute
  * @param config - The inferredAssignments configuration
  */
-export async function processInferredAssignments(
+export function processInferredAssignments(
     target: any,
     from: any,
     config: InferredAssignmentsConfig
-): Promise<void> {
+): void {
     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 async 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/markerUtils.js

@@ -1,127 +1,136 @@
-/**
- * markerUtils.js — Shared utilities for comment marker management.
- *
- * Used by lazyLoad, microDataJoin, and future template loop handlers.
- */
-
-export const MARKER_START_PREFIX = '?start name="';
-export const MARKER_END = '?end';
-
-/**
- * Find existing start/end comment markers (TreeWalker approach).
- */
-export function findMarkers(target, name) {
-    const startText = `${MARKER_START_PREFIX}${name}"`;
-    let startMarker = null;
-    let endMarker = null;
-
-    const walker = document.createTreeWalker(target, NodeFilter.SHOW_COMMENT);
-    let node;
-    while ((node = walker.nextNode())) {
-        if (!startMarker && node.data === startText) {
-            startMarker = node;
-        } else if (startMarker && !endMarker && node.data === MARKER_END) {
-            endMarker = node;
-            break;
-        }
-    }
-
-    return [startMarker, endMarker];
-}
-
-/**
- * Find existing start/end comment markers (XPath approach).
- */
-export function findMarkersXPath(target, name) {
-    const startText = `${MARKER_START_PREFIX}${name}"`;
-
-    const startResult = document.evaluate(
-        `.//comment()[. = "${startText}"]`,
-        target,
-        null,
-        XPathResult.FIRST_ORDERED_NODE_TYPE,
-        null
-    );
-    const startMarker = startResult.singleNodeValue;
-    if (!startMarker) return [null, null];
-
-    const endResult = document.evaluate(
-        `following-sibling::comment()[. = "${MARKER_END}"][1]`,
-        startMarker,
-        null,
-        XPathResult.FIRST_ORDERED_NODE_TYPE,
-        null
-    );
-    const endMarker = endResult.singleNodeValue;
-
-    return [startMarker, endMarker];
-}
-
-/**
- * Create start/end markers and insert them into the target.
- */
-export function createMarkers(target, name, method = 'appendChild') {
-    const startMarker = document.createComment(`${MARKER_START_PREFIX}${name}"`);
-    const endMarker = document.createComment(MARKER_END);
-
-    if (method === 'prepend') {
-        target.prepend(endMarker);
-        target.prepend(startMarker);
-    } else {
-        target.appendChild(startMarker);
-        target.appendChild(endMarker);
-    }
-
-    return [startMarker, endMarker];
-}
-
-/**
- * Get all nodes between start and end markers.
- */
-export function getNodesBetweenMarkers(start, end) {
-    const nodes = [];
-    let current = start.nextSibling;
-    while (current && current !== end) {
-        nodes.push(current);
-        current = current.nextSibling;
-    }
-    return nodes;
-}
-
-/**
- * Find existing start/end comment markers among siblings of an anchor element.
- * Used for 'after' insertion mode.
- */
-export function findMarkersSibling(anchor, name) {
-    const startText = `${MARKER_START_PREFIX}${name}"`;
-    let startMarker = null;
-    let endMarker = null;
-
-    let current = anchor.nextSibling;
-    while (current) {
-        if (current.nodeType === Node.COMMENT_NODE) {
-            if (!startMarker && current.data === startText) {
-                startMarker = current;
-            } else if (startMarker && !endMarker && current.data === MARKER_END) {
-                endMarker = current;
-                break;
-            }
-        }
-        current = current.nextSibling;
-    }
-
-    return [startMarker, endMarker];
-}
-
-/**
- * Create start/end markers as siblings after an anchor element.
- * Used for 'after' insertion mode.
- */
-export function createMarkersSibling(anchor, name) {
-    const startMarker = document.createComment(`${MARKER_START_PREFIX}${name}"`);
-    const endMarker = document.createComment(MARKER_END);
-
-    anchor.after(startMarker, endMarker);
-
-    return [startMarker, endMarker];
-}
+/**
+ * markerUtils.ts — Shared utilities for comment marker management.
+ *
+ * Used by lazyLoad, microDataJoin, and future template loop handlers.
+ * Provides finding, creating, and traversing comment marker pairs.
+ *
+ * Markers are HTML comment nodes with specific content:
+ * - Start: <!--?start name="markerName"-->
+ * - End:   <!--?end-->
+ */
+export const MARKER_START_PREFIX = '?start name="';
+export const MARKER_END = '?end';
+/**
+ * Find existing start/end comment markers in a target element (TreeWalker approach).
+ * Searches the subtree of `target` for matching comment nodes.
+ *
+ * @param target - The element to search within
+ * @param name - The marker name to find
+ * @returns [startMarker, endMarker] or [null, null] if not found
+ */
+export function findMarkers(target, name) {
+    const startText = `${MARKER_START_PREFIX}${name}"`;
+    let startMarker = null;
+    let endMarker = null;
+    const walker = document.createTreeWalker(target, NodeFilter.SHOW_COMMENT);
+    let node;
+    while ((node = walker.nextNode())) {
+        if (!startMarker && node.data === startText) {
+            startMarker = node;
+        }
+        else if (startMarker && !endMarker && node.data === MARKER_END) {
+            endMarker = node;
+            break;
+        }
+    }
+    return [startMarker, endMarker];
+}
+/**
+ * Find existing start/end comment markers using XPath (alternative approach).
+ * May be faster in large DOMs due to engine-level indexing.
+ *
+ * @param target - The element to search within
+ * @param name - The marker name to find
+ * @returns [startMarker, endMarker] or [null, null] if not found
+ */
+export function findMarkersXPath(target, name) {
+    const startText = `${MARKER_START_PREFIX}${name}"`;
+    const startResult = document.evaluate(`.//comment()[. = "${startText}"]`, target, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
+    const startMarker = startResult.singleNodeValue;
+    if (!startMarker)
+        return [null, null];
+    // Find the next sibling comment that is the end marker
+    const endResult = document.evaluate(`following-sibling::comment()[. = "${MARKER_END}"][1]`, startMarker, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
+    const endMarker = endResult.singleNodeValue;
+    return [startMarker, endMarker];
+}
+/**
+ * Create start/end markers and insert them into the target.
+ *
+ * @param target - The element to insert markers into
+ * @param name - The marker name
+ * @param method - 'appendChild' (default) or 'prepend'
+ * @returns [startMarker, endMarker]
+ */
+export function createMarkers(target, name, method = 'appendChild') {
+    const startMarker = document.createComment(`${MARKER_START_PREFIX}${name}"`);
+    const endMarker = document.createComment(MARKER_END);
+    if (method === 'prepend') {
+        target.prepend(endMarker);
+        target.prepend(startMarker);
+    }
+    else {
+        target.appendChild(startMarker);
+        target.appendChild(endMarker);
+    }
+    return [startMarker, endMarker];
+}
+/**
+ * Get all nodes between start and end markers.
+ *
+ * @param start - The start comment marker
+ * @param end - The end comment marker
+ * @returns Array of nodes between the markers (exclusive of markers themselves)
+ */
+export function getNodesBetweenMarkers(start, end) {
+    const nodes = [];
+    let current = start.nextSibling;
+    while (current && current !== end) {
+        nodes.push(current);
+        current = current.nextSibling;
+    }
+    return nodes;
+}
+/**
+ * Find existing start/end comment markers among siblings of an anchor element.
+ * Used for 'after' insertion mode where markers are siblings, not children.
+ *
+ * @param anchor - The element after which markers were inserted
+ * @param name - The marker name to find
+ * @returns [startMarker, endMarker] or [null, null] if not found
+ */
+export function findMarkersSibling(anchor, name) {
+    const startText = `${MARKER_START_PREFIX}${name}"`;
+    let startMarker = null;
+    let endMarker = null;
+    let current = anchor.nextSibling;
+    while (current) {
+        if (current.nodeType === Node.COMMENT_NODE) {
+            const comment = current;
+            if (!startMarker && comment.data === startText) {
+                startMarker = comment;
+            }
+            else if (startMarker && !endMarker && comment.data === MARKER_END) {
+                endMarker = comment;
+                break;
+            }
+        }
+        current = current.nextSibling;
+    }
+    return [startMarker, endMarker];
+}
+/**
+ * Create start/end markers as siblings after an anchor element.
+ * Used for 'after' insertion mode.
+ *
+ * @param anchor - The element to insert markers after
+ * @param name - The marker name
+ * @returns [startMarker, endMarker]
+ */
+export function createMarkersSibling(anchor, name) {
+    const startMarker = document.createComment(`${MARKER_START_PREFIX}${name}"`);
+    const endMarker = document.createComment(MARKER_END);
+    // Insert after the anchor: anchor → startMarker → endMarker
+    anchor.after(startMarker, endMarker);
+    return [startMarker, endMarker];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.58",
+  "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": {
@@ -62,6 +62,10 @@
       "default": "./resolveValues.js",
       "types": "./resolveValues.ts"
     },
+    "./getValues.js": {
+      "default": "./getValues.js",
+      "types": "./getValues.ts"
+    },
     "./resolveIdRef.js": {
       "default": "./resolveIdRef.js",
       "types": "./resolveIdRef.ts"
@@ -98,6 +102,10 @@
       "default": "./handlers/microDataJoin.js",
       "types": "./handlers/microDataJoin.ts"
     },
+    "./handlers/manageTemplateList.js": {
+      "default": "./handlers/manageTemplateList.js",
+      "types": "./handlers/manageTemplateList.ts"
+    },
     "./paths.js": {
       "default": "./paths.js",
       "types": "./paths.ts"
@@ -114,6 +122,10 @@
       "default": "./markerUtils.js",
       "types": "./markerUtils.ts"
     },
+    "./waitForSettled.js": {
+      "default": "./waitForSettled.js",
+      "types": "./waitForSettled.ts"
+    },
     "./inferredAssignments.js": {
       "default": "./inferredAssignments.js",
       "types": "./inferredAssignments.ts"
@@ -130,10 +142,26 @@
       "default": "./inferencer/withScopePerimeter.js",
       "types": "./inferencer/withScopePerimeter.ts"
     },
+    "./assignFromAsync.js": {
+      "default": "./assignFromAsync.js",
+      "types": "./assignFromAsync.ts"
+    },
     "./assignFrom.js": {
       "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"
@@ -148,6 +176,7 @@
   "scripts": {
     "serve": "node ./node_modules/spa-ssi/serve.js",
     "test": "playwright test",
+    "benchmark": "playwright test tests/benchmark.spec.ts --reporter=list --project=chromium",
     "update": "ncu -u && npm install",
     "safari": "npx playwright wk http://localhost:8000",
     "chrome": "npx playwright cr http://localhost:8000"

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

@@ -4,6 +4,7 @@
  * Dynamically imported only when ` =>` keys are detected in the pattern.
  */
 import { resolveValues } from './resolveValues.js';
+import { getValues } from './getValues.js';
 import { evaluatePathWithMethods } from './assignGingerly.js';
 import { isAllowedImportPath } from './isAllowedImportPath.js';
 /**
@@ -15,6 +16,7 @@ const BUILT_IN_MAP = {
     'builtIns.lazyLoadSwitch': './handlers/lazyLoadSwitch.js',
     'builtIns.join': './handlers/join.js',
     'builtIns.microDataJoin': './handlers/microDataJoin.js',
+    'builtIns.manageTemplateList': './handlers/manageTemplateList.js',
 };
 /**
  * Find a handler class in a dynamically imported module.
@@ -35,16 +37,27 @@ function findHandlerInModule(module) {
     }
     return undefined;
 }
+/**
+ * Cache for loaded built-in handler classes — avoids await on subsequent calls.
+ */
+const handlerCache = new Map();
 /**
  * Dynamically load a built-in handler by name.
  * Returns the handler constructor, or undefined if the name isn't a recognized built-in.
+ * Cached after first load — subsequent calls are synchronous.
  */
 async function loadBuiltIn(name) {
+    const cached = handlerCache.get(name);
+    if (cached)
+        return cached;
     const path = BUILT_IN_MAP[name];
     if (!path)
         return undefined;
     const module = await import(path);
-    return findHandlerInModule(module);
+    const cls = findHandlerInModule(module);
+    if (cls)
+        handlerCache.set(name, cls);
+    return cls;
 }
 /**
  * Resolve a handler from options.handlers (class constructor or import path).
@@ -57,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). ` +
@@ -157,27 +175,41 @@ export async function processHandlerCommands(target, handlerKeys, pattern, optio
         }
         // Execute handlers sequentially, sharing the same lhsTarget
         for (const config of configs) {
+            //return; //1.3ms
             // 1. Check options.handlers (local, per-call)
             let HandlerClass = await resolveFromHandlers(config.do, options.handlers, permissions);
+            //return; // 1.4
             // 2. Fallback to built-in auto-load
             if (!HandlerClass && config.do.startsWith('builtIns.')) {
                 HandlerClass = await loadBuiltIn(config.do);
             }
+            //return; //1.4
             if (!HandlerClass) {
                 throw new Error(`assignFrom: unknown handler "${config.do}". Provide it in options.handlers.`);
             }
-            // Resolve 'resolve' map if present — uses full resolveValues (paths, protocols, literals)
+            // Resolve 'get' map synchronously (no thread yield)
             let resolvedParams = {};
+            if (config.get) {
+                resolvedParams = getValues(config.get, options.from, {
+                    withMethods: options.withMethods,
+                    aka: options.aka,
+                    protocols: options.protocols
+                });
+            }
+            // Resolve 'resolve' map asynchronously (yields to microtask queue)
             if (config.resolve) {
-                resolvedParams = await resolveValues(config.resolve, options.from, {
+                const asyncResolved = await resolveValues(config.resolve, options.from, {
                     withMethods: options.withMethods,
                     aka: options.aka,
                     protocols: options.protocols
                 });
+                Object.assign(resolvedParams, asyncResolved);
             }
             // Instantiate and invoke the handler
             const handler = new HandlerClass(config);
+            //return; //1.5ms
             const result = await handler.assign(lhsTarget, resolvedParams, options);
+            //return; //1.5ms
             // Return-value protocol: if handler returns a non-undefined value,
             // assign it back to the LHS path
             if (result !== undefined && lhsParent != null && lhsKey != null) {