assign-gingerly 0.0.53 → 0.0.55

package/processHandlerCommands.ts

@@ -0,0 +1,217 @@
+/**
+ * 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 { isAllowedImportPath } from './isAllowedImportPath.js';
+import type { AssignPermissions } from './isAllowedImportPath.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',
+};
+
+/**
+ * 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,
+    permissions?: AssignPermissions
+): 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 (!permissions?.crossDomainImports && !isAllowedImportPath(entry)) {
+            throw new Error(
+                `assignFrom: handler "${name}" has an invalid import path "${entry}". ` +
+                `Only relative, absolute, or bare specifier paths are allowed (no cross-domain URLs). ` +
+                `Pass { crossDomainImports: true } in permissions to override.`
+            );
+        }
+        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,
+    permissions?: AssignPermissions
+): 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, permissions);
+
+            // 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,144 @@
+/**
+ * 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).
+ */
+/**
+ * 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 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) {
+    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 };
+}
+/**
+ * Register an element in the WeakRef cache for fast subsequent access.
+ * Auto-assigns an ID if the element doesn't have one.
+ *
+ * Used by beVigilant to cache newly discovered elements so that future
+ * assignFrom calls can resolve them via getElementById/WeakRef.
+ *
+ * @param target - The target element (used to determine rootNode)
+ * @param varName - The cache key (typically the itemprop name)
+ * @param element - The element to cache
+ */
+export function registerInCache(target, varName, element) {
+    const rootNode = target.getRootNode?.() ?? target;
+    let cache = idCacheMap.get(rootNode);
+    if (!cache) {
+        cache = new Map();
+        idCacheMap.set(rootNode, cache);
+    }
+    // Ensure the element has an ID
+    let id = element.id;
+    if (!id) {
+        id = generateUniqueId(rootNode);
+        element.id = id;
+    }
+    cache.set(varName, { id, ref: new WeakRef(element) });
+}

package/resolveIdRef.ts

@@ -0,0 +1,170 @@
+/**
+ * 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 };
+}
+
+/**
+ * Register an element in the WeakRef cache for fast subsequent access.
+ * Auto-assigns an ID if the element doesn't have one.
+ * 
+ * Used by beVigilant to cache newly discovered elements so that future
+ * assignFrom calls can resolve them via getElementById/WeakRef.
+ * 
+ * @param target - The target element (used to determine rootNode)
+ * @param varName - The cache key (typically the itemprop name)
+ * @param element - The element to cache
+ */
+export function registerInCache(target: any, varName: string, element: Element): void {
+    const rootNode = target.getRootNode?.() ?? target;
+
+    let cache = idCacheMap.get(rootNode);
+    if (!cache) {
+        cache = new Map();
+        idCacheMap.set(rootNode, cache);
+    }
+
+    // Ensure the element has an ID
+    let id = element.id;
+    if (!id) {
+        id = generateUniqueId(rootNode);
+        element.id = id;
+    }
+
+    cache.set(varName, { id, ref: new WeakRef(element) });
+}

package/resolveValues.js

@@ -98,6 +98,40 @@ function navigatePath(source, parts, withMethods) {
     }
     return current;
 }
+/**
+ * Resolve path strings and protocol references within an array.
+ * Recurses into nested arrays and plain objects. Non-string elements,
+ * class instances, and other non-plain objects pass through unchanged.
+ */
+async function resolveArray(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(await resolveProtocolValue(item, protocols, options));
+        }
+        else if (Array.isArray(item)) {
+            result.push(await resolveArray(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(await resolveValues(item, source, options));
+            }
+            else {
+                result.push(item);
+            }
+        }
+        else {
+            result.push(item);
+        }
+    }
+    return result;
+}
 /**
  * Resolve RHS path strings in a pattern object against a source object.
  *
@@ -160,13 +194,18 @@ export async function resolveValues(pattern, source, options) {
             // Protocol-prefixed value — resolve asynchronously
             result[key] = await resolveProtocolValue(value, protocols, options);
         }
-        else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        else if (Array.isArray(value)) {
+            // Resolve path strings and protocols within arrays (recursing into nested arrays)
+            result[key] = await resolveArray(value, source, aliasMap, withMethods, protocols, options);
+        }
+        else if (typeof value === 'object' && value !== null) {
             // Recursively resolve nested plain objects (e.g., headers: { "...": "globalThis://key" })
             // Only recurse into plain objects — skip DOM elements, class instances, etc.
             const proto = Object.getPrototypeOf(value);
             if (proto === Object.prototype || proto === null) {
                 result[key] = await resolveValues(value, source, options);
-            } else {
+            }
+            else {
                 result[key] = value;
             }
         }

package/resolveValues.ts

@@ -147,6 +147,43 @@ function navigatePath(
   return current;
 }
 
+/**
+ * Resolve path strings and protocol references within an array.
+ * Recurses into nested arrays and plain objects. Non-string elements,
+ * class instances, and other non-plain objects pass through unchanged.
+ */
+async function resolveArray(
+  arr: any[],
+  source: any,
+  aliasMap: Map<string, string>,
+  withMethods: Set<string> | undefined,
+  protocols: Record<string, (key: string) => any | Promise<any>> | undefined,
+  options?: ResolveValuesOptions
+): Promise<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(await resolveProtocolValue(item, protocols, options));
+    } else if (Array.isArray(item)) {
+      result.push(await resolveArray(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(await resolveValues(item, source, options));
+      } else {
+        result.push(item);
+      }
+    } else {
+      result.push(item);
+    }
+  }
+  return result;
+}
+
 /**
  * Resolve RHS path strings in a pattern object against a source object.
  * 
@@ -216,7 +253,10 @@ export async function resolveValues(
     } else if (typeof value === 'string' && protocols && hasProtocol(value)) {
       // Protocol-prefixed value — resolve asynchronously
       result[key] = await resolveProtocolValue(value, protocols, options);
-    } else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+    } else if (Array.isArray(value)) {
+      // Resolve path strings and protocols within arrays (recursing into nested arrays)
+      result[key] = await resolveArray(value, source, aliasMap, withMethods, protocols, options);
+    } else if (typeof value === 'object' && value !== null) {
       // Recursively resolve nested plain objects (e.g., headers: { "...": "globalThis://key" })
       // Only recurse into plain objects — skip DOM elements, class instances, etc.
       const proto = Object.getPrototypeOf(value);