assign-gingerly 0.0.57 → 0.0.59

package/handlers/manageTemplateList.ts

@@ -0,0 +1,240 @@
+/**
+ * builtIns.manageTemplateList handler for assignFrom.
+ * 
+ * Clones a template once per item in an iterable, distributing each item's
+ * properties into its clone via assignFrom. Manages the list over time —
+ * reconciling by key to add, remove, and update-in-place.
+ * 
+ * This handler is auto-loaded by processHandlerCommands when
+ * `do: 'builtIns.manageTemplateList'` is encountered.
+ * 
+ * @example
+ * assignFrom(document.body, {
+ *     '?.querySelector?.tbody =>': {
+ *         do: 'builtIns.manageTemplateList',
+ *         resolve: {
+ *             forEach: '?.rankings',
+ *             instantiate: 'globalThis://country-ranking',
+ *         },
+ *         fromEachItem: {
+ *             assignToFragment: { '?.querySelector?.tr?.ish': '?.' },
+ *             withOptions: { withMethods: ['querySelector'], inferredAssignments: true },
+ *             resolve: { key: '?.rank' }
+ *         }
+ *     }
+ * }, { from: vm, withMethods: ['querySelector'], protocols: { globalThis: k => globalThis[k] } });
+ */
+
+import type { AssignFromHandler } from '../assignFromAsync.js';
+import type { ManageTemplateListResolvedParams } from '../types/assign-gingerly/types.js';
+import { findMarkers, createMarkers, getNodesBetweenMarkers, MARKER_START_PREFIX, MARKER_END } from '../markerUtils.js';
+import { resolveValue } from '../resolveValues.js';
+import { assignFrom } from '../assignFrom.js';
+import { processInferredAssignments } from '../inferredAssignments.js';
+
+/**
+ * State stored per list instance (keyed by start marker).
+ * Tracks the mapping of keys to their cloned DOM nodes.
+ */
+interface ListState {
+    /** Map of key value → array of DOM nodes for that item's clone */
+    keyToNodes: Map<any, Node[]>;
+    /** Ordered array of keys matching current DOM order */
+    keyOrder: any[];
+}
+
+const listStateMap = new WeakMap<Node, ListState>();
+
+/**
+ * ManageTemplateListHandler — clones a template per iterable item with keyed reconciliation.
+ */
+export class ManageTemplateListHandler implements AssignFromHandler {
+    config: any;
+
+    constructor(config: any) {
+        this.config = config;
+    }
+
+    async assign(lhsTarget: any, resolvedParams: ManageTemplateListResolvedParams, options?: any): Promise<void> {
+        //return;
+        const {
+            forEach: items,
+            instantiate,
+            method = 'appendChild',
+            forget = false,
+            markerName,
+            yieldEvery,
+        } = resolvedParams;
+
+        if (!(lhsTarget instanceof Element)) {
+            throw new Error('builtIns.manageTemplateList: lhsTarget must be a DOM Element');
+        }
+
+        if (!items || typeof items[Symbol.iterator] !== 'function') {
+            return; // Nothing to iterate
+        }
+
+        const fromEachItem = this.config.fromEachItem;
+        const assignToFragment = fromEachItem?.assignToFragment ?? {};
+        const withOptions = fromEachItem?.withOptions ?? {};
+        const perItemResolve = fromEachItem?.resolve ?? {};
+        const keyPath = perItemResolve.key; // e.g., '?.rank'
+
+        // fromSource config — assigns from the outer `from` (parent VM) to each clone
+        const fromSource = this.config.fromSource;
+        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;
+
+        const name = markerName ?? getMarkerName(instantiate) ?? 'templateList';
+
+        // Find or create markers
+        let [startMarker, endMarker] = findMarkers(lhsTarget, name);
+        if (!startMarker || !endMarker) {
+            [startMarker, endMarker] = createMarkers(lhsTarget, name, method);
+        }
+
+        // Get or create list state
+        let state = listStateMap.get(startMarker);
+        if (!state) {
+            state = { keyToNodes: new Map(), keyOrder: [] };
+            listStateMap.set(startMarker, state);
+        }
+
+        // Convert iterable to array
+        const itemsArray = Array.from(items);
+
+        // Fast path: use processInferredAssignments directly when possible
+        const processInferred = useFastPath ? processInferredAssignments : null;
+        const newKeys: any[] = itemsArray.map((item, index) => {
+            if (keyPath) {
+                return resolveValue(keyPath, item);
+            }
+            return index; // Positional fallback when no key specified
+        });
+
+        // Determine what changed
+        const oldKeys = new Set(state.keyOrder);
+        const newKeySet = new Set(newKeys);
+
+        // Keys to remove
+        for (const oldKey of state.keyOrder) {
+            if (!newKeySet.has(oldKey)) {
+                const nodes = state.keyToNodes.get(oldKey);
+                if (nodes) {
+                    if (forget) {
+                        for (const node of nodes) node.parentNode?.removeChild(node);
+                    } else {
+                        for (const node of nodes) {
+                            if (node instanceof Element) node.setAttribute('hidden', '');
+                        }
+                    }
+                    state.keyToNodes.delete(oldKey);
+                }
+            }
+        }
+
+        // Process items — clone new ones, update existing
+        const fragment = document.createDocumentFragment();
+        const newKeyToNodes = new Map<any, Node[]>();
+
+        for (let i = 0; i < itemsArray.length; i++) {
+            const item = itemsArray[i];
+            const key = newKeys[i];
+
+            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 });
+                    }
+                    if (sourceAssignToFragment && options?.from) {
+                        assignFrom(rootEl, sourceAssignToFragment, { from: options.from, ...sourceWithOptions });
+                    }
+                }
+                newKeyToNodes.set(key, existingNodes);
+                for (const node of existingNodes) {
+                    if (node instanceof Element) node.removeAttribute('hidden');
+                }
+            } else {
+                // New item — clone template
+                let content: DocumentFragment;
+                if (instantiate instanceof HTMLTemplateElement) {
+                    content = instantiate.content.cloneNode(true) as DocumentFragment;
+                } else if (instantiate instanceof DocumentFragment) {
+                    content = instantiate.cloneNode(true) as DocumentFragment;
+                } else {
+                    throw new Error('builtIns.manageTemplateList: instantiate must be an HTMLTemplateElement or DocumentFragment');
+                }
+
+                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 });
+                    }
+
+                    if (sourceAssignToFragment && options?.from) {
+                        assignFrom(rootEl, sourceAssignToFragment, { from: options.from, ...sourceWithOptions });
+                    }
+                }
+
+                for (const node of clonedNodes) {
+                    fragment.appendChild(node);
+                }
+                newKeyToNodes.set(key, clonedNodes);
+            }
+        }
+
+        // Wait for async rendering in the fragment to settle before committing
+        if (fragment.childNodes.length > 0) {
+            const waitOpt = resolvedParams.waitForSettled;
+            if (waitOpt) {
+                const { waitForSettled } = await import('../waitForSettled.js');
+                const idleMs = typeof waitOpt === 'object' ? waitOpt.idleMs : 100;
+                const timeout = typeof waitOpt === 'object' ? waitOpt.timeout : undefined;
+                try {
+                    await waitForSettled(fragment, idleMs, timeout);
+                } catch (e) {
+                    console.warn('builtIns.manageTemplateList:', (e as Error).message, '— inserting fragment anyway');
+                }
+            }
+
+            // Insert new fragment before end marker
+            endMarker.parentNode!.insertBefore(fragment, endMarker);
+        }
+
+        // Update state
+        state.keyToNodes = newKeyToNodes;
+        state.keyOrder = newKeys;
+    }
+}
+
+/**
+ * Get marker name from a template element.
+ */
+function getMarkerName(templateEl: any): string | undefined {
+    if (templateEl instanceof HTMLTemplateElement) {
+        return templateEl.id || undefined;
+    }
+    return undefined;
+}

package/handlers/microDataJoin.ts

@@ -33,7 +33,7 @@
  * }, { from: vm, withMethods: ['querySelector'] });
  */
 
-import type { AssignFromHandler } from '../assignFrom.js';
+import type { AssignFromHandler } from '../assignFromAsync.js';
 
 const MARKER_START_PREFIX = '?start name="';
 const MARKER_END = '?end';

package/index.js

@@ -8,6 +8,7 @@ export { buildCSSQuery } from './buildCSSQuery.js';
 export { resolveTemplate } from './resolveTemplate.js';
 export { getHost } from './getHost.js';
 export { resolveValues, resolveValue } from './resolveValues.js';
+export { assignFromAsync } from './assignFromAsync.js';
 export { assignFrom } from './assignFrom.js';
 export { assignFeatures, FeaturesRegistry, captureFeatureInitVals, PropertyBag, suggestFeatureInfo, getFeatureInfoSuggestions } from './assignFeatures.js';
 export { installForwarding } from './installForwarding.js';

package/index.ts

@@ -8,9 +8,11 @@ export {buildCSSQuery} from './buildCSSQuery.js';
 export {resolveTemplate} from './resolveTemplate.js';
 export {getHost} from './getHost.js';
 export {resolveValues, resolveValue} from './resolveValues.js';
+export {assignFromAsync} from './assignFromAsync.js';
 export {assignFrom} from './assignFrom.js';
 export {assignFeatures, FeaturesRegistry, captureFeatureInitVals, PropertyBag, suggestFeatureInfo, getFeatureInfoSuggestions} from './assignFeatures.js';
 export {installForwarding} from './installForwarding.js';
 export {defineWithFeatures} from './defineWithFeatures.js';
 export {resolveAndAssignFeatures} from './resolveAndAssignFeatures.js';
+export {} from './handlers/manageTemplateList.js';
 import './object-extension.js';

package/inferredAssignments.js

@@ -12,7 +12,7 @@ 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')

package/inferredAssignments.ts

@@ -31,11 +31,11 @@ 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;
 

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.57",
+  "version": "0.0.59",
   "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,6 +142,10 @@
       "default": "./inferencer/withScopePerimeter.js",
       "types": "./inferencer/withScopePerimeter.ts"
     },
+    "./assignFromAsync.js": {
+      "default": "./assignFromAsync.js",
+      "types": "./assignFromAsync.ts"
+    },
     "./assignFrom.js": {
       "default": "./assignFrom.js",
       "types": "./assignFrom.ts"
@@ -148,6 +164,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"