assign-gingerly 0.0.57 → 0.0.59

package/getValues.ts

@@ -0,0 +1,255 @@
+/**
+ * getValues.ts — Synchronous value resolution for path strings.
+ * 
+ * The synchronous counterpart to resolveValues. Resolves `?.`-prefixed path
+ * strings against a source object, with support for withMethods, aka aliases,
+ * synchronous protocols, arrays, and nested plain objects.
+ * 
+ * For async protocol handlers, use resolveValues instead.
+ * 
+ * @example
+ * import { getValues, getValue } from 'assign-gingerly/getValues.js';
+ * 
+ * const result = getValues({
+ *     name: '?.user?.name',
+ *     greeting: '?.messages?.hello',
+ *     count: 42
+ * }, source, { withMethods: ['querySelector'], aka: { q: 'querySelector' } });
+ */
+
+import type { GetValuesOptions } from './types/assign-gingerly/types.js';
+
+/**
+ * Apply alias substitutions to a path string.
+ * Replaces complete tokens between `?.` delimiters with their aliased values.
+ */
+function applyAliases(path: string, aliasMap: Map<string, string>): string {
+    if (aliasMap.size === 0) return path;
+    const parts = path.split('?.');
+    const substituted = parts.map(part => aliasMap.get(part) ?? part);
+    return substituted.join('?.');
+}
+
+/**
+ * Path cache for parsed path strings.
+ * Avoids re-splitting the same path on repeated calls.
+ */
+const pathCache = new Map<string, string[]>();
+
+/**
+ * Parse a `?.`-delimited path string into segments, with caching.
+ */
+function parseCachedPath(path: string): string[] {
+    let parts = pathCache.get(path);
+    if (!parts) {
+        parts = path.split('?.').filter(p => p.length > 0);
+        pathCache.set(path, parts);
+    }
+    return parts;
+}
+
+/**
+ * Navigate a path against a source object, optionally calling methods.
+ * Returns the resolved value at the end of the path.
+ */
+function navigatePath(
+    source: any,
+    parts: string[],
+    withMethods: Set<string> | undefined
+): any {
+    let current = source;
+    let i = 0;
+
+    while (i < parts.length) {
+        if (current == null) return current;
+
+        const part = parts[i];
+
+        if (withMethods && withMethods.has(part)) {
+            const method = current[part];
+            if (typeof method === 'function') {
+                const nextPart = parts[i + 1];
+                if (nextPart !== undefined && !(withMethods.has(nextPart))) {
+                    current = method.call(current, nextPart);
+                    i += 2;
+                } else {
+                    current = method.call(current);
+                    i++;
+                }
+            } else {
+                current = current[part];
+                i++;
+            }
+        } else {
+            current = current[part];
+            i++;
+        }
+    }
+
+    return current;
+}
+
+/**
+ * Checks if a string value looks like a protocol reference.
+ */
+function hasProtocol(value: string): boolean {
+    return value.includes('://');
+}
+
+/**
+ * Resolve a protocol-prefixed value synchronously.
+ */
+function getProtocolValue(
+    value: string,
+    protocols: Record<string, (key: string) => any>,
+    options?: GetValuesOptions
+): any {
+    const protoEnd = value.indexOf('://');
+    const protocol = value.substring(0, protoEnd);
+
+    const handler = protocols[protocol];
+    if (!handler) return value; // not a recognized protocol
+
+    const rest = value.substring(protoEnd + 3);
+
+    const pathStart = rest.indexOf('?.');
+    const key = pathStart === -1 ? rest : rest.substring(0, pathStart);
+    const path = pathStart === -1 ? null : rest.substring(pathStart);
+
+    const resolved = handler(key);
+
+    if (path) {
+        return getValue(path, resolved, options);
+    }
+    return resolved;
+}
+
+/**
+ * Resolve path strings and protocols within an array (synchronous).
+ * Recurses into nested arrays and plain objects.
+ */
+function getArray(
+    arr: any[],
+    source: any,
+    aliasMap: Map<string, string>,
+    withMethods: Set<string> | undefined,
+    protocols: Record<string, (key: string) => any> | undefined,
+    options?: GetValuesOptions
+): any[] {
+    const result: any[] = [];
+    for (const item of arr) {
+        if (typeof item === 'string' && item.startsWith('?.')) {
+            const aliased = applyAliases(item, aliasMap);
+            const parts = parseCachedPath(aliased);
+            result.push(parts.length === 0 ? source : navigatePath(source, parts, withMethods));
+        } else if (typeof item === 'string' && protocols && hasProtocol(item)) {
+            result.push(getProtocolValue(item, protocols, options));
+        } else if (Array.isArray(item)) {
+            result.push(getArray(item, source, aliasMap, withMethods, protocols, options));
+        } else if (item && typeof item === 'object') {
+            const proto = Object.getPrototypeOf(item);
+            if (proto === Object.prototype || proto === null) {
+                result.push(getValues(item, source, options));
+            } else {
+                result.push(item);
+            }
+        } else {
+            result.push(item);
+        }
+    }
+    return result;
+}
+
+/**
+ * Synchronously resolve RHS path strings in a pattern object against a source object.
+ * 
+ * Any value that is a string starting with `?.` is treated as a path
+ * and resolved against the source object. Non-string values and strings
+ * not starting with `?.` pass through unchanged.
+ * 
+ * @param pattern - Object whose RHS values may contain `?.` path strings
+ * @param source - Object to resolve paths against
+ * @param options - Optional withMethods, aka, and synchronous protocols
+ * @returns New object with path strings replaced by resolved values
+ */
+export function getValues(
+    pattern: Record<string, any>,
+    source: any,
+    options?: GetValuesOptions
+): Record<string, any> {
+    // Build alias map
+    const aliasMap = new Map<string, string>();
+    if (options?.aka) {
+        for (const [alias, target] of Object.entries(options.aka)) {
+            aliasMap.set(alias, target);
+        }
+    }
+
+    // Build methods set
+    const withMethods = options?.withMethods
+        ? options.withMethods instanceof Set
+            ? options.withMethods
+            : new Set(options.withMethods)
+        : undefined;
+
+    const protocols = options?.protocols;
+
+    const result: Record<string, any> = {};
+    for (const [key, value] of Object.entries(pattern)) {
+        if (typeof value === 'string' && value.startsWith('?.')) {
+            const aliased = applyAliases(value, aliasMap);
+            const parts = parseCachedPath(aliased);
+            result[key] = parts.length === 0 ? source : navigatePath(source, parts, withMethods);
+        } else if (typeof value === 'string' && protocols && hasProtocol(value)) {
+            result[key] = getProtocolValue(value, protocols, options);
+        } else if (Array.isArray(value)) {
+            result[key] = getArray(value, source, aliasMap, withMethods, protocols, options);
+        } else if (typeof value === 'object' && value !== null) {
+            const proto = Object.getPrototypeOf(value);
+            if (proto === Object.prototype || proto === null) {
+                result[key] = getValues(value, source, options);
+            } else {
+                result[key] = value;
+            }
+        } else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+
+/**
+ * Synchronously resolve a single `?.`-delimited path string against a source object.
+ * 
+ * @param path - A `?.`-delimited path string (e.g., '?.user?.name')
+ * @param source - Object to resolve the path against
+ * @param options - Optional withMethods and aka
+ * @returns The resolved value, or undefined if any segment is nullish
+ */
+export function getValue(
+    path: string,
+    source: any,
+    options?: GetValuesOptions
+): any {
+    if (!path.startsWith('?.')) return path;
+
+    let aliased = path;
+    if (options?.aka) {
+        const aliasMap = new Map<string, string>();
+        for (const [alias, target] of Object.entries(options.aka)) {
+            aliasMap.set(alias, target);
+        }
+        aliased = applyAliases(path, aliasMap);
+    }
+
+    const parts = parseCachedPath(aliased);
+    if (parts.length === 0) return source;
+
+    const withMethods = options?.withMethods
+        ? options.withMethods instanceof Set
+            ? options.withMethods
+            : new Set(options.withMethods)
+        : undefined;
+
+    return navigatePath(source, parts, withMethods);
+}

package/handlers/join.ts

@@ -31,7 +31,7 @@
  * // If middleName is undefined, the sub-array [', ', undefined] is dropped entirely.
  */
 
-import type { AssignFromHandler } from '../assignFrom.js';
+import type { AssignFromHandler } from '../assignFromAsync.js';
 
 /**
  * Process nested arrays with all-or-nothing null semantics.

package/handlers/lazyLoad.js

@@ -73,7 +73,7 @@ export class LazyLoadHandler {
                 }
                 else {
                     if (transitional) {
-                        ensureHideStyle(lhsTarget.getRootNode());
+                        ensureHideStyle(lhsTarget.getRootNode(), hideClass, hideCss);
                         withTransition(startMarker, 'show', true, () => {
                             this.cloneAndInsertSync(instantiate, startMarker, endMarker, lhsTarget, resolvedParams);
                         });
@@ -89,7 +89,7 @@ export class LazyLoadHandler {
                     [startMarker, endMarker] = createMarkers(lhsTarget, name, method);
                 }
                 if (transitional) {
-                    ensureHideStyle(lhsTarget.getRootNode());
+                    ensureHideStyle(lhsTarget.getRootNode(), hideClass, hideCss);
                     withTransition(startMarker, 'show', true, () => {
                         this.cloneAndInsertSync(instantiate, startMarker, endMarker, lhsTarget, resolvedParams);
                     });

package/handlers/lazyLoad.ts

@@ -19,7 +19,7 @@
  * }, { withMethods: ['querySelector'], from: myVM });
  */
 
-import type { AssignFromHandler } from '../assignFrom.js';
+import type { AssignFromHandler } from '../assignFromAsync.js';
 import type { LazyLoadResolvedParams, LazyLoadInstantiatedContext } from '../types/assign-gingerly/types.js';
 import { withTransition, ensureHideStyle, DEFAULT_HIDE_CLASS } from '../transitionHelper.js';
 import { findMarkers, createMarkers, getNodesBetweenMarkers, findMarkersSibling, createMarkersSibling, MARKER_START_PREFIX, MARKER_END } from '../markerUtils.js';
@@ -102,7 +102,7 @@ export class LazyLoadHandler implements AssignFromHandler {
                 } else {
                     // Content was removed (forget mode) — re-clone
                     if (transitional) {
-                        ensureHideStyle(lhsTarget.getRootNode());
+                        ensureHideStyle(lhsTarget.getRootNode(), hideClass, hideCss);
                         withTransition(startMarker, 'show', true, () => {
                             this.cloneAndInsertSync(instantiate, startMarker!, endMarker!, lhsTarget, resolvedParams);
                         });
@@ -118,7 +118,7 @@ export class LazyLoadHandler implements AssignFromHandler {
                     [startMarker, endMarker] = createMarkers(lhsTarget, name, method);
                 }
                 if (transitional) {
-                    ensureHideStyle(lhsTarget.getRootNode());
+                    ensureHideStyle(lhsTarget.getRootNode(), hideClass, hideCss);
                     withTransition(startMarker, 'show', true, () => {
                         this.cloneAndInsertSync(instantiate, startMarker!, endMarker!, lhsTarget, resolvedParams);
                     });

package/handlers/lazyLoadSwitch.ts

@@ -21,7 +21,7 @@
  */
 
 import { LazyLoadHandler } from './lazyLoad.js';
-import type { AssignFromHandler } from '../assignFrom.js';
+import type { AssignFromHandler } from '../assignFromAsync.js';
 import type { LazyLoadSwitchResolvedParams } from '../types/assign-gingerly/types.js';
 
 /**

package/handlers/manageTemplateList.js

@@ -0,0 +1,203 @@
+/**
+ * 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 { findMarkers, createMarkers } from '../markerUtils.js';
+import { resolveValue } from '../resolveValues.js';
+import { assignFrom } from '../assignFrom.js';
+import { processInferredAssignments } from '../inferredAssignments.js';
+const listStateMap = new WeakMap();
+/**
+ * ManageTemplateListHandler — clones a template per iterable item with keyed reconciliation.
+ */
+export class ManageTemplateListHandler {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async assign(lhsTarget, resolvedParams, options) {
+        //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 = 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();
+        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);
+                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;
+                if (instantiate instanceof HTMLTemplateElement) {
+                    content = instantiate.content.cloneNode(true);
+                }
+                else if (instantiate instanceof DocumentFragment) {
+                    content = instantiate.cloneNode(true);
+                }
+                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);
+                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.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) {
+    if (templateEl instanceof HTMLTemplateElement) {
+        return templateEl.id || undefined;
+    }
+    return undefined;
+}