assign-gingerly 0.0.52 → 0.0.54

package/processHandlerCommands.js

@@ -0,0 +1,188 @@
+/**
+ * processHandlerCommands - Handles ` =>` operator keys in assignFrom.
+ *
+ * Dynamically imported only when ` =>` keys are detected in the pattern.
+ */
+import { resolveValues } from './resolveValues.js';
+import { evaluatePathWithMethods } from './assignGingerly.js';
+/**
+ * Map of built-in handler names to their module paths.
+ * These are auto-loaded on demand — no explicit import required.
+ */
+const BUILT_IN_MAP = {
+    'builtIns.lazyLoad': './handlers/lazyLoad.js',
+    'builtIns.lazyLoadSwitch': './handlers/lazyLoadSwitch.js',
+    'builtIns.join': './handlers/join.js',
+    'builtIns.microDataJoin': './handlers/microDataJoin.js',
+};
+/**
+ * Check if an import path is allowed (non-cross-domain).
+ */
+function isAllowedImportPath(path) {
+    return path.startsWith('./') || path.startsWith('../') || path.startsWith('/')
+        || (!path.includes('://') && !path.startsWith('//'));
+}
+/**
+ * Find a handler class in a dynamically imported module.
+ * Checks default export first, then searches for the first class with `assign` on prototype.
+ */
+function findHandlerInModule(module) {
+    if (module.default && typeof module.default === 'function'
+        && module.default.prototype && 'assign' in module.default.prototype) {
+        return module.default;
+    }
+    for (const key of Object.keys(module)) {
+        const exported = module[key];
+        if (typeof exported === 'function' && exported.prototype && 'assign' in exported.prototype) {
+            return exported;
+        }
+    }
+    return undefined;
+}
+/**
+ * Dynamically load a built-in handler by name.
+ */
+async function loadBuiltIn(name) {
+    const path = BUILT_IN_MAP[name];
+    if (!path)
+        return undefined;
+    const module = await import(path);
+    return findHandlerInModule(module);
+}
+/**
+ * Resolve a handler from options.handlers (class constructor or import path).
+ */
+async function resolveFromHandlers(name, handlers) {
+    if (!handlers || !(name in handlers))
+        return undefined;
+    const entry = handlers[name];
+    if (typeof entry === 'function') {
+        return entry;
+    }
+    if (typeof entry === 'string') {
+        if (!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).`
+            );
+        }
+        const module = await import(entry);
+        const HandlerClass = findHandlerInModule(module);
+        if (!HandlerClass) {
+            throw new Error(
+                `assignFrom: handler "${name}" — module "${entry}" does not export a valid handler class.`
+            );
+        }
+        return HandlerClass;
+    }
+    return undefined;
+}
+/**
+ * Process all handler command keys (ending with ' =>') in a pattern.
+ *
+ * @param target - The target object being assigned to
+ * @param handlerKeys - Array of keys ending with ' =>'
+ * @param pattern - The original pattern object
+ * @param options - The assignFrom options
+ */
+export async function processHandlerCommands(target, handlerKeys, pattern, options) {
+    for (const key of handlerKeys) {
+        const lhsPath = key.substring(0, key.length - 3); // Remove ' =>'
+        const rhs = pattern[key];
+        // Normalize RHS to an array of handler configs
+        const configs = Array.isArray(rhs) ? rhs : [rhs];
+        // Validate — no nested arrays
+        for (const config of configs) {
+            if (Array.isArray(config)) {
+                throw new Error(`assignFrom: handler command "${key}" does not support nested arrays`);
+            }
+            if (!config || typeof config !== 'object' || !config.do) {
+                throw new Error(`assignFrom: handler command "${key}" requires a config object with a "do" field`);
+            }
+        }
+        // Empty array — skip silently
+        if (configs.length === 0)
+            continue;
+        // Resolve the LHS path, preserving parent + key for return-value assignment.
+        let lhsTarget;
+        let lhsParent = undefined;
+        let lhsKey = undefined;
+        if (lhsPath.startsWith('?.')) {
+            const pathParts = lhsPath.split('?.').filter(p => p.length > 0);
+            const withMethodsSet = options.withMethods
+                ? options.withMethods instanceof Set
+                    ? options.withMethods
+                    : new Set(options.withMethods)
+                : undefined;
+            if (withMethodsSet && pathParts.length > 0) {
+                const result = evaluatePathWithMethods(target, pathParts, undefined, withMethodsSet);
+                lhsParent = result.target;
+                lhsKey = result.lastKey;
+                lhsTarget = result.target[result.lastKey];
+                if (result.isMethod && typeof result.target[result.lastKey] === 'function') {
+                    lhsTarget = result.target[result.lastKey].call(result.target);
+                    lhsParent = undefined;
+                    lhsKey = undefined;
+                }
+            }
+            else {
+                if (pathParts.length === 0) {
+                    lhsTarget = target;
+                }
+                else if (pathParts.length === 1) {
+                    lhsParent = target;
+                    lhsKey = pathParts[0];
+                    lhsTarget = target[pathParts[0]];
+                }
+                else {
+                    let current = target;
+                    for (let i = 0; i < pathParts.length - 1; i++) {
+                        if (current == null)
+                            break;
+                        current = current[pathParts[i]];
+                    }
+                    lhsParent = current;
+                    lhsKey = pathParts[pathParts.length - 1];
+                    lhsTarget = current != null ? current[lhsKey] : undefined;
+                }
+            }
+        }
+        else if (lhsPath) {
+            lhsParent = target;
+            lhsKey = lhsPath;
+            lhsTarget = target[lhsPath];
+        }
+        else {
+            lhsTarget = target;
+        }
+        // Execute handlers sequentially, sharing the same lhsTarget
+        for (const config of configs) {
+            // 1. Check options.handlers (local, per-call)
+            let HandlerClass = await resolveFromHandlers(config.do, options.handlers);
+            // 2. Fallback to built-in auto-load
+            if (!HandlerClass && config.do.startsWith('builtIns.')) {
+                HandlerClass = await loadBuiltIn(config.do);
+            }
+            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)
+            let resolvedParams = {};
+            if (config.resolve) {
+                resolvedParams = await resolveValues(config.resolve, options.from, {
+                    withMethods: options.withMethods,
+                    aka: options.aka,
+                    protocols: options.protocols
+                });
+            }
+            // Instantiate and invoke the handler
+            const handler = new HandlerClass(config);
+            const result = await handler.assign(lhsTarget, resolvedParams, options);
+            // Return-value protocol: if handler returns a non-undefined value,
+            // assign it back to the LHS path
+            if (result !== undefined && lhsParent != null && lhsKey != null) {
+                lhsParent[lhsKey] = result;
+            }
+        }
+    }
+}

package/processHandlerCommands.ts

@@ -0,0 +1,220 @@
+/**
+ * processHandlerCommands - Handles ` =>` operator keys in assignFrom.
+ * 
+ * Dynamically imported only when ` =>` keys are detected in the pattern.
+ */
+
+import { resolveValues } from './resolveValues.js';
+import { evaluatePathWithMethods } from './assignGingerly.js';
+import type { AssignFromOptions, AssignFromHandlerConstructor } from './assignFrom.js';
+
+/**
+ * Map of built-in handler names to their module paths.
+ * These are auto-loaded on demand — no explicit import required.
+ */
+const BUILT_IN_MAP: Record<string, string> = {
+    'builtIns.lazyLoad': './handlers/lazyLoad.js',
+    'builtIns.lazyLoadSwitch': './handlers/lazyLoadSwitch.js',
+    'builtIns.join': './handlers/join.js',
+    'builtIns.microDataJoin': './handlers/microDataJoin.js',
+};
+
+/**
+ * Check if an import path is allowed (non-cross-domain).
+ */
+function isAllowedImportPath(path: string): boolean {
+    return path.startsWith('./') || path.startsWith('../') || path.startsWith('/')
+        || (!path.includes('://') && !path.startsWith('//'));
+}
+
+/**
+ * Find a handler class in a dynamically imported module.
+ * Checks default export first, then searches for the first class with `assign` on prototype.
+ */
+function findHandlerInModule(module: any): AssignFromHandlerConstructor | undefined {
+    // Check default export first
+    if (module.default && typeof module.default === 'function'
+        && module.default.prototype && 'assign' in module.default.prototype) {
+        return module.default;
+    }
+    // Search other exports
+    for (const key of Object.keys(module)) {
+        const exported = module[key];
+        if (typeof exported === 'function' && exported.prototype && 'assign' in exported.prototype) {
+            return exported as AssignFromHandlerConstructor;
+        }
+    }
+    return undefined;
+}
+
+/**
+ * Dynamically load a built-in handler by name.
+ * Returns the handler constructor, or undefined if the name isn't a recognized built-in.
+ */
+async function loadBuiltIn(name: string): Promise<AssignFromHandlerConstructor | undefined> {
+    const path = BUILT_IN_MAP[name];
+    if (!path) return undefined;
+    const module = await import(path);
+    return findHandlerInModule(module);
+}
+
+/**
+ * Resolve a handler from options.handlers (class constructor or import path).
+ */
+async function resolveFromHandlers(
+    name: string,
+    handlers: Record<string, AssignFromHandlerConstructor | string> | undefined
+): Promise<AssignFromHandlerConstructor | undefined> {
+    if (!handlers || !(name in handlers)) return undefined;
+
+    const entry = handlers[name];
+
+    // Class constructor — use directly
+    if (typeof entry === 'function') {
+        return entry as AssignFromHandlerConstructor;
+    }
+
+    // Import path string — validate and dynamically import
+    if (typeof entry === 'string') {
+        if (!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).`
+            );
+        }
+        const module = await import(entry);
+        const HandlerClass = findHandlerInModule(module);
+        if (!HandlerClass) {
+            throw new Error(
+                `assignFrom: handler "${name}" — module "${entry}" does not export a valid handler class.`
+            );
+        }
+        return HandlerClass;
+    }
+
+    return undefined;
+}
+
+/**
+ * Process all handler command keys (ending with ' =>') in a pattern.
+ * 
+ * @param target - The target object being assigned to
+ * @param handlerKeys - Array of keys ending with ' =>'
+ * @param pattern - The original pattern object
+ * @param options - The assignFrom options
+ * @param handlerRegistry - The registry of handler classes
+ */
+export async function processHandlerCommands(
+    target: any,
+    handlerKeys: string[],
+    pattern: Record<string, any>,
+    options: AssignFromOptions
+): Promise<void> {
+    for (const key of handlerKeys) {
+        const lhsPath = key.substring(0, key.length - 3); // Remove ' =>'
+        const rhs = pattern[key];
+
+        // Normalize RHS to an array of handler configs
+        const configs = Array.isArray(rhs) ? rhs : [rhs];
+
+        // Validate — no nested arrays
+        for (const config of configs) {
+            if (Array.isArray(config)) {
+                throw new Error(`assignFrom: handler command "${key}" does not support nested arrays`);
+            }
+            if (!config || typeof config !== 'object' || !config.do) {
+                throw new Error(`assignFrom: handler command "${key}" requires a config object with a "do" field`);
+            }
+        }
+
+        // Empty array — skip silently
+        if (configs.length === 0) continue;
+
+        // Resolve the LHS path, preserving parent + key for return-value assignment.
+        // lhsParent[lhsKey] === lhsTarget (the current value at the path)
+        let lhsTarget: any;
+        let lhsParent: any = undefined;
+        let lhsKey: string | undefined = undefined;
+
+        if (lhsPath.startsWith('?.')) {
+            const pathParts = lhsPath.split('?.').filter(p => p.length > 0);
+            const withMethodsSet = options.withMethods
+                ? options.withMethods instanceof Set
+                    ? options.withMethods
+                    : new Set(options.withMethods)
+                : undefined;
+
+            if (withMethodsSet && pathParts.length > 0) {
+                const result = evaluatePathWithMethods(target, pathParts, undefined, withMethodsSet);
+                lhsParent = result.target;
+                lhsKey = result.lastKey;
+                lhsTarget = result.target[result.lastKey];
+                // If last key is a method, call it to get the target
+                if (result.isMethod && typeof result.target[result.lastKey] === 'function') {
+                    lhsTarget = result.target[result.lastKey].call(result.target);
+                    lhsParent = undefined; // Can't assign back to a method call result
+                    lhsKey = undefined;
+                }
+            } else {
+                // Simple path navigation — walk to parent, keep last key
+                if (pathParts.length === 0) {
+                    lhsTarget = target;
+                } else if (pathParts.length === 1) {
+                    lhsParent = target;
+                    lhsKey = pathParts[0];
+                    lhsTarget = target[pathParts[0]];
+                } else {
+                    let current = target;
+                    for (let i = 0; i < pathParts.length - 1; i++) {
+                        if (current == null) break;
+                        current = current[pathParts[i]];
+                    }
+                    lhsParent = current;
+                    lhsKey = pathParts[pathParts.length - 1];
+                    lhsTarget = current != null ? current[lhsKey] : undefined;
+                }
+            }
+        } else if (lhsPath) {
+            lhsParent = target;
+            lhsKey = lhsPath;
+            lhsTarget = target[lhsPath];
+        } else {
+            lhsTarget = target;
+        }
+
+        // Execute handlers sequentially, sharing the same lhsTarget
+        for (const config of configs) {
+            // 1. Check options.handlers (local, per-call)
+            let HandlerClass = await resolveFromHandlers(config.do, options.handlers);
+
+            // 2. Fallback to built-in auto-load
+            if (!HandlerClass && config.do.startsWith('builtIns.')) {
+                HandlerClass = await loadBuiltIn(config.do);
+            }
+
+            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)
+            let resolvedParams: Record<string, any> = {};
+            if (config.resolve) {
+                resolvedParams = await resolveValues(config.resolve, options.from, {
+                    withMethods: options.withMethods,
+                    aka: options.aka,
+                    protocols: options.protocols
+                });
+            }
+
+            // Instantiate and invoke the handler
+            const handler = new HandlerClass(config);
+            const result = await handler.assign(lhsTarget, resolvedParams, options);
+
+            // Return-value protocol: if handler returns a non-undefined value,
+            // assign it back to the LHS path
+            if (result !== undefined && lhsParent != null && lhsKey != null) {
+                lhsParent[lhsKey] = result;
+            }
+        }
+    }
+}

package/resolveIdRef.js

@@ -0,0 +1,125 @@
+/**
+ * resolveIdRef.js — Cached element resolution via #[x] syntax.
+ *
+ * Dynamically imported by assignFrom when `withIds` is provided or `#[x]` patterns are detected.
+ * Provides lazy, WeakRef-cached element lookups keyed by variable name.
+ *
+ * First access: runs the query against the target, auto-assigns an ID if needed, caches via WeakRef.
+ * Subsequent access: WeakRef.deref() (~10ns) or getElementById fallback (~20-100ns).
+ */
+
+/**
+ * Module-level cache: rootNode → Map<varName, { id, WeakRef }>
+ * WeakMap ensures cleanup when rootNode is GC'd.
+ */
+const idCacheMap = new WeakMap();
+
+/**
+ * Counter per rootNode for generating unique IDs.
+ */
+const idCounterMap = new WeakMap();
+
+/**
+ * Generate a unique ID within a rootNode.
+ * Format: _ag0, _ag1, _ag2, ...
+ */
+function generateUniqueId(rootNode) {
+    let counter = idCounterMap.get(rootNode) ?? 0;
+    let id;
+    // Ensure uniqueness (skip if ID already exists in the document)
+    do {
+        id = `_ag${counter}`;
+        counter++;
+    } while (rootNode.getElementById?.(id));
+    idCounterMap.set(rootNode, counter);
+    return id;
+}
+
+/**
+ * Resolve a single #[varName] reference lazily.
+ *
+ * @param varName - The variable name (e.g., 'x' from '#[x]')
+ * @param target - The target element to query against
+ * @param withIds - The withIds configuration map
+ * @returns The resolved element, or undefined if not found
+ */
+export function resolveIdVariable(varName, target, withIds) {
+    const config = withIds[varName];
+    if (config === undefined) return undefined;
+
+    const rootNode = target.getRootNode?.() ?? target;
+
+    // Get or create cache for this rootNode
+    let cache = idCacheMap.get(rootNode);
+    if (!cache) {
+        cache = new Map();
+        idCacheMap.set(rootNode, cache);
+    }
+
+    // Check cache first
+    const cached = cache.get(varName);
+    if (cached) {
+        const el = cached.ref.deref();
+        if (el) return el;
+
+        // WeakRef was collected — try getElementById fallback
+        const el2 = rootNode.getElementById?.(cached.id);
+        if (el2) {
+            cache.set(varName, { id: cached.id, ref: new WeakRef(el2) });
+            return el2;
+        }
+        // Element no longer exists — fall through to re-query
+    }
+
+    // First time or cache miss — resolve the element
+    let el = null;
+
+    if (typeof config === 'string') {
+        // String form: existing ID — use getElementById directly
+        el = rootNode.getElementById?.(config) ?? null;
+    } else {
+        // Object form: { qry } — run querySelector against target
+        el = target.querySelector?.(config.qry) ?? null;
+    }
+
+    if (!el) return undefined;
+
+    // Ensure the element has an ID
+    let id = el.id;
+    if (!id) {
+        id = generateUniqueId(rootNode);
+        el.id = id;
+    }
+
+    // Cache it
+    cache.set(varName, { id, ref: new WeakRef(el) });
+    return el;
+}
+
+/**
+ * Check if a key starts with #[...] syntax.
+ */
+export function hasIdRef(key) {
+    return key.startsWith('#[');
+}
+
+/**
+ * Extract the variable name and remaining path from a #[x]... key.
+ * Returns { varName, remainingPath } or null if not valid.
+ */
+export function parseIdRef(key) {
+    const closeIdx = key.indexOf(']');
+    if (closeIdx === -1) return null;
+
+    const varName = key.substring(2, closeIdx); // skip '#['
+    if (!varName) return null;
+
+    let remainingPath = key.substring(closeIdx + 1);
+
+    // Remove handler suffix if present (caller handles it separately)
+    if (remainingPath.endsWith(' =>')) {
+        remainingPath = remainingPath.substring(0, remainingPath.length - 3);
+    }
+
+    return { varName, remainingPath };
+}

package/resolveIdRef.ts

@@ -0,0 +1,140 @@
+/**
+ * resolveIdRef.ts — Cached element resolution via #[x] syntax.
+ * 
+ * Dynamically imported by assignFrom when `withIds` is provided or `#[x]` patterns are detected.
+ * Provides lazy, WeakRef-cached element lookups keyed by variable name.
+ * 
+ * First access: runs the query against the target, auto-assigns an ID if needed, caches via WeakRef.
+ * Subsequent access: WeakRef.deref() (~10ns) or getElementById fallback (~20-100ns).
+ */
+
+/**
+ * Configuration for a withIds entry.
+ */
+export type WithIdConfig = string | { qry: string };
+
+/**
+ * Module-level cache: rootNode → Map<varName, { id, WeakRef }>
+ * WeakMap ensures cleanup when rootNode is GC'd.
+ */
+const idCacheMap = new WeakMap<object, Map<string, { id: string; ref: WeakRef<Element> }>>();
+
+/**
+ * Counter per rootNode for generating unique IDs.
+ */
+const idCounterMap = new WeakMap<object, number>();
+
+/**
+ * Generate a unique ID within a rootNode.
+ * Format: _ag0, _ag1, _ag2, ...
+ */
+function generateUniqueId(rootNode: any): string {
+    let counter = idCounterMap.get(rootNode) ?? 0;
+    let id: string;
+    // Ensure uniqueness (skip if ID already exists in the document)
+    do {
+        id = `_ag${counter}`;
+        counter++;
+    } while (rootNode.getElementById?.(id));
+    idCounterMap.set(rootNode, counter);
+    return id;
+}
+
+/**
+ * Resolve a single #[varName] reference lazily.
+ * 
+ * @param varName - The variable name (e.g., 'x' from '#[x]')
+ * @param target - The target element to query against
+ * @param withIds - The withIds configuration map
+ * @returns The resolved element, or undefined if not found
+ */
+export function resolveIdVariable(
+    varName: string,
+    target: any,
+    withIds: Record<string, WithIdConfig>
+): Element | undefined {
+    const config = withIds[varName];
+    if (config === undefined) return undefined;
+
+    const rootNode = target.getRootNode?.() ?? target;
+
+    // Get or create cache for this rootNode
+    let cache = idCacheMap.get(rootNode);
+    if (!cache) {
+        cache = new Map();
+        idCacheMap.set(rootNode, cache);
+    }
+
+    // Check cache first
+    const cached = cache.get(varName);
+    if (cached) {
+        const el = cached.ref.deref();
+        if (el) return el;
+
+        // WeakRef was collected — try getElementById fallback
+        const el2 = rootNode.getElementById?.(cached.id);
+        if (el2) {
+            cache.set(varName, { id: cached.id, ref: new WeakRef(el2) });
+            return el2;
+        }
+        // Element no longer exists — fall through to re-query
+    }
+
+    // First time or cache miss — resolve the element
+    let el: Element | null = null;
+
+    if (typeof config === 'string') {
+        // String form: existing ID — use getElementById directly
+        el = rootNode.getElementById?.(config) ?? null;
+    } else {
+        // Object form: { qry } — run querySelector against target
+        el = target.querySelector?.(config.qry) ?? null;
+    }
+
+    if (!el) return undefined;
+
+    // Ensure the element has an ID
+    let id = el.id;
+    if (!id) {
+        id = generateUniqueId(rootNode);
+        el.id = id;
+    }
+
+    // Cache it
+    cache.set(varName, { id, ref: new WeakRef(el) });
+    return el;
+}
+
+/**
+ * Check if a key starts with #[...] syntax.
+ */
+export function hasIdRef(key: string): boolean {
+    return key.startsWith('#[');
+}
+
+/**
+ * Extract the variable name and remaining path from a #[x]... key.
+ * Returns [varName, remainingPath] or null if not a valid #[x] reference.
+ * 
+ * Examples:
+ *   '#[x]' → ['x', '']
+ *   '#[x] =>' → ['x', '']  (handler suffix handled separately)
+ *   '#[x]?.querySelector?..child' → ['x', '?.querySelector?..child']
+ *   '#[x]?.textContent =>' → ['x', '?.textContent']  (handler suffix handled separately)
+ */
+export function parseIdRef(key: string): { varName: string; remainingPath: string } | null {
+    const closeIdx = key.indexOf(']');
+    if (closeIdx === -1) return null;
+
+    const varName = key.substring(2, closeIdx); // skip '#['
+    if (!varName) return null;
+
+    let remainingPath = key.substring(closeIdx + 1);
+
+    // Remove handler suffix if present (caller handles it separately)
+    if (remainingPath.endsWith(' =>')) {
+        remainingPath = remainingPath.substring(0, remainingPath.length - 3);
+    }
+
+    return { varName, remainingPath };
+}