assign-gingerly 0.0.58 → 0.0.60

package/getValues.js

@@ -0,0 +1,223 @@
+/**
+ * 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' } });
+ */
+/**
+ * Apply alias substitutions to a path string.
+ * Replaces complete tokens between `?.` delimiters with their aliased values.
+ */
+function applyAliases(path, aliasMap) {
+    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();
+/**
+ * Parse a `?.`-delimited path string into segments, with caching.
+ */
+function parseCachedPath(path) {
+    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, parts, withMethods) {
+    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) {
+    return value.includes('://');
+}
+/**
+ * Resolve a protocol-prefixed value synchronously.
+ */
+function getProtocolValue(value, protocols, options) {
+    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, source, aliasMap, withMethods, protocols, options) {
+    const result = [];
+    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, source, options) {
+    // Build alias map
+    const aliasMap = new Map();
+    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 = {};
+    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, source, options) {
+    if (!path.startsWith('?.'))
+        return path;
+    let aliased = path;
+    if (options?.aka) {
+        const aliasMap = new Map();
+        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/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

@@ -37,14 +37,17 @@ function getMarkerName(templateEl) {
  *
  * Exported so it can be subclassed for custom behavior.
  */
+import { assignFrom } from '../assignFrom.js';
 export class LazyLoadHandler {
     config;
+    _options;
     static #markerCounter = 0;
     constructor(config) {
         this.config = config;
     }
-    async assign(lhsTarget, resolvedParams) {
-        const { if: condition, instantiate, method = 'appendChild', forget = false, transitional = false, hideClass = DEFAULT_HIDE_CLASS, hideCss, markerName, toggleInert = false, toggleDisabled = false } = resolvedParams;
+    async assign(lhsTarget, resolvedParams, options) {
+        this._options = options;
+        const { if: condition, instantiate, method = 'appendChild', forget = false, transitional = false, hideClass = DEFAULT_HIDE_CLASS, hideCss, markerName, toggleInert = false, toggleDisabled = false, placeholder } = resolvedParams;
         if (!(lhsTarget instanceof Element)) {
             throw new Error('builtIns.lazyLoad: lhsTarget must be a DOM Element');
         }
@@ -83,6 +86,16 @@ export class LazyLoadHandler {
                 }
             }
             else {
+                // Remove placeholder content if specified
+                if (placeholder) {
+                    const [phStart, phEnd] = findMarkers(lhsTarget, placeholder);
+                    if (phStart && phEnd) {
+                        const phNodes = getNodesBetweenMarkers(phStart, phEnd);
+                        for (const node of phNodes) {
+                            node.parentNode?.removeChild(node);
+                        }
+                    }
+                }
                 if (method === 'after') {
                     [startMarker, endMarker] = createMarkersSibling(lhsTarget, name);
                 } else {
@@ -164,6 +177,7 @@ export class LazyLoadHandler {
             throw new Error(`builtIns.lazyLoad: instantiate must resolve to an HTMLTemplateElement or DocumentFragment`);
         }
         const nodes = Array.from(content.childNodes);
+        this.applyAssign(nodes, resolvedParams);
         endMarker.parentNode.insertBefore(content, endMarker);
         return nodes;
     }
@@ -179,6 +193,7 @@ export class LazyLoadHandler {
             throw new Error(`builtIns.lazyLoad: instantiate must resolve to an HTMLTemplateElement or DocumentFragment`);
         }
         const nodes = Array.from(content.childNodes);
+        this.applyAssign(nodes, resolvedParams);
         endMarker.parentNode.insertBefore(content, endMarker);
         await this.onCloneInserted(nodes, lhsTarget, resolvedParams);
         if (resolvedParams.onInstantiated && typeof resolvedParams.onInstantiated === 'function') {
@@ -192,6 +207,22 @@ export class LazyLoadHandler {
         }
         return nodes;
     }
+    applyAssign(nodes, resolvedParams) {
+        const assign = resolvedParams.assign;
+        if (!assign) return;
+        const elements = nodes.filter(n => n instanceof Element);
+        if (elements.length === 0) return;
+        const from = this._options?.from ?? {};
+        if (assign.configs && Array.isArray(assign.configs)) {
+            const len = Math.min(elements.length, assign.configs.length);
+            for (let j = 0; j < len; j++) {
+                const cfg = assign.configs[j];
+                assignFrom(elements[j], cfg.assignToFragment ?? {}, { from, ...cfg.withOptions });
+            }
+        } else if (assign.assignToFragment) {
+            assignFrom(elements[0], assign.assignToFragment, { from, ...assign.withOptions });
+        }
+    }
     async onCloneInserted(nodes, lhsTarget, resolvedParams) {
         // No-op by default. Subclasses override.
     }

package/handlers/lazyLoad.ts

@@ -19,10 +19,11 @@
  * }, { 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';
+import { assignFrom } from '../assignFrom.js';
 
 export type { LazyLoadResolvedParams, LazyLoadInstantiatedContext };
 
@@ -46,13 +47,15 @@ function getMarkerName(templateEl: any): string {
  */
 export class LazyLoadHandler implements AssignFromHandler {
     config: any;
+    _options: any;
     static #markerCounter = 0;
 
     constructor(config: any) {
         this.config = config;
     }
 
-    async assign(lhsTarget: any, resolvedParams: LazyLoadResolvedParams): Promise<void> {
+    async assign(lhsTarget: any, resolvedParams: LazyLoadResolvedParams, options?: any): Promise<void> {
+        this._options = options; // Store for applyAssign access
         const {
             if: condition,
             instantiate,
@@ -64,6 +67,7 @@ export class LazyLoadHandler implements AssignFromHandler {
             markerName,
             toggleInert = false,
             toggleDisabled = false,
+            placeholder,
         } = resolvedParams;
 
         if (!(lhsTarget instanceof Element)) {
@@ -112,6 +116,16 @@ export class LazyLoadHandler implements AssignFromHandler {
                 }
             } else {
                 // No markers — first time. Create markers and clone template.
+                // Remove placeholder content if specified
+                if (placeholder) {
+                    const [phStart, phEnd] = findMarkers(lhsTarget, placeholder);
+                    if (phStart && phEnd) {
+                        const phNodes = getNodesBetweenMarkers(phStart, phEnd);
+                        for (const node of phNodes) {
+                            node.parentNode?.removeChild(node);
+                        }
+                    }
+                }
                 if (method === 'after') {
                     [startMarker, endMarker] = createMarkersSibling(lhsTarget, name);
                 } else {
@@ -229,6 +243,10 @@ export class LazyLoadHandler implements AssignFromHandler {
         }
 
         const nodes = Array.from(content.childNodes);
+
+        // Apply assignments to cloned content before insertion
+        this.applyAssign(nodes, resolvedParams);
+
         endMarker.parentNode!.insertBefore(content, endMarker);
         return nodes;
     }
@@ -259,6 +277,9 @@ export class LazyLoadHandler implements AssignFromHandler {
         // Capture nodes before insertion (childNodes empties after insertBefore)
         const nodes = Array.from(content.childNodes);
 
+        // Apply assignments to cloned content before insertion
+        this.applyAssign(nodes, resolvedParams);
+
         // Insert before endMarker
         endMarker.parentNode!.insertBefore(content, endMarker);
 
@@ -279,6 +300,30 @@ export class LazyLoadHandler implements AssignFromHandler {
         return nodes;
     }
 
+    /**
+     * Apply assignFrom to cloned nodes based on the `assign` config.
+     * Supports single-element and multi-element (configs array) templates.
+     */
+    protected applyAssign(nodes: Node[], resolvedParams: LazyLoadResolvedParams): void {
+        const assign = (resolvedParams as any).assign;
+        if (!assign) return;
+
+        const elements = nodes.filter(n => n instanceof Element) as Element[];
+        if (elements.length === 0) return;
+
+        const from = this._options?.from ?? {};
+
+        if (assign.configs && Array.isArray(assign.configs)) {
+            const len = Math.min(elements.length, assign.configs.length);
+            for (let j = 0; j < len; j++) {
+                const cfg = assign.configs[j];
+                assignFrom(elements[j], cfg.assignToFragment ?? {}, { from, ...cfg.withOptions });
+            }
+        } else if (assign.assignToFragment) {
+            assignFrom(elements[0], assign.assignToFragment, { from, ...assign.withOptions });
+        }
+    }
+
     /**
      * Hook called after template content is cloned and inserted.
      * Override in subclasses for custom post-clone logic.

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';
 
 /**