assign-gingerly 0.0.58 → 0.0.60

package/processHandlerCommands.ts

@@ -5,10 +5,11 @@
  */
 
 import { resolveValues } from './resolveValues.js';
+import { getValues } from './getValues.js';
 import { evaluatePathWithMethods } from './assignGingerly.js';
 import { isAllowedImportPath } from './isAllowedImportPath.js';
 import type { AssignPermissions } from './isAllowedImportPath.js';
-import type { AssignFromOptions, AssignFromHandlerConstructor } from './assignFrom.js';
+import type { AssignFromOptions, AssignFromHandlerConstructor } from './assignFromAsync.js';
 
 /**
  * Map of built-in handler names to their module paths.
@@ -19,6 +20,7 @@ const BUILT_IN_MAP: Record<string, string> = {
     'builtIns.lazyLoadSwitch': './handlers/lazyLoadSwitch.js',
     'builtIns.join': './handlers/join.js',
     'builtIns.microDataJoin': './handlers/microDataJoin.js',
+    'builtIns.manageTemplateList': './handlers/manageTemplateList.js',
 };
 
 /**
@@ -41,15 +43,25 @@ function findHandlerInModule(module: any): AssignFromHandlerConstructor | undefi
     return undefined;
 }
 
+/**
+ * Cache for loaded built-in handler classes — avoids await on subsequent calls.
+ */
+const handlerCache = new Map<string, AssignFromHandlerConstructor>();
+
 /**
  * Dynamically load a built-in handler by name.
  * Returns the handler constructor, or undefined if the name isn't a recognized built-in.
+ * Cached after first load — subsequent calls are synchronous.
  */
 async function loadBuiltIn(name: string): Promise<AssignFromHandlerConstructor | undefined> {
+    const cached = handlerCache.get(name);
+    if (cached) return cached;
     const path = BUILT_IN_MAP[name];
     if (!path) return undefined;
     const module = await import(path);
-    return findHandlerInModule(module);
+    const cls = findHandlerInModule(module);
+    if (cls) handlerCache.set(name, cls);
+    return cls;
 }
 
 /**
@@ -69,8 +81,14 @@ async function resolveFromHandlers(
         return entry as AssignFromHandlerConstructor;
     }
 
-    // Import path string — validate and dynamically import
+    // String value — could be a built-in alias or an import path
     if (typeof entry === 'string') {
+        // Built-in alias: redirect to built-in loader
+        if (entry.startsWith('builtIns.')) {
+            return loadBuiltIn(entry);
+        }
+
+        // Import path string — validate and dynamically import
         if (!permissions?.crossDomainImports && !isAllowedImportPath(entry)) {
             throw new Error(
                 `assignFrom: handler "${name}" has an invalid import path "${entry}". ` +
@@ -107,6 +125,7 @@ export async function processHandlerCommands(
     options: AssignFromOptions,
     permissions?: AssignPermissions
 ): Promise<void> {
+    
     for (const key of handlerKeys) {
         const lhsPath = key.substring(0, key.length - 3); // Remove ' =>'
         const rhs = pattern[key];
@@ -178,35 +197,46 @@ export async function processHandlerCommands(
         } else {
             lhsTarget = target;
         }
-
         // Execute handlers sequentially, sharing the same lhsTarget
         for (const config of configs) {
+            //return; //1.3ms
             // 1. Check options.handlers (local, per-call)
             let HandlerClass = await resolveFromHandlers(config.do, options.handlers, permissions);
-
+            //return; // 1.4
             // 2. Fallback to built-in auto-load
             if (!HandlerClass && config.do.startsWith('builtIns.')) {
                 HandlerClass = await loadBuiltIn(config.do);
             }
+            //return; //1.4
 
             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)
+            // Resolve 'get' map synchronously (no thread yield)
             let resolvedParams: Record<string, any> = {};
+            if (config.get) {
+                resolvedParams = getValues(config.get, options.from, {
+                    withMethods: options.withMethods,
+                    aka: options.aka,
+                    protocols: options.protocols
+                });
+            }
+            // Resolve 'resolve' map asynchronously (yields to microtask queue)
             if (config.resolve) {
-                resolvedParams = await resolveValues(config.resolve, options.from, {
+                const asyncResolved = await resolveValues(config.resolve, options.from, {
                     withMethods: options.withMethods,
                     aka: options.aka,
                     protocols: options.protocols
                 });
+                Object.assign(resolvedParams, asyncResolved);
             }
 
             // Instantiate and invoke the handler
             const handler = new HandlerClass(config);
+            //return; //1.5ms
             const result = await handler.assign(lhsTarget, resolvedParams, options);
-
+            //return; //1.5ms
             // Return-value protocol: if handler returns a non-undefined value,
             // assign it back to the LHS path
             if (result !== undefined && lhsParent != null && lhsKey != null) {

package/resolveIdRef.js

@@ -18,14 +18,15 @@ const idCacheMap = new WeakMap();
 const idCounterMap = new WeakMap();
 /**
  * Generate a unique ID within a rootNode.
- * Format: _ag0, _ag1, _ag2, ...
+ * Format: -ag:0, -ag:1, -ag:2, ...
+ * Starts with '-' and contains ':' to avoid collision with JS identifiers/globalThis properties.
  */
 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}`;
+        id = `-ag:${counter}`;
         counter++;
     } while (rootNode.getElementById?.(id));
     idCounterMap.set(rootNode, counter);
@@ -43,6 +44,55 @@ export function resolveIdVariable(varName, target, withIds) {
     const config = withIds[varName];
     if (config === undefined)
         return undefined;
+    // For 'at' option path-based configs (array or { path }), resolve directly from target — no ID, no caching
+    // These are target-relative and fast (~2-4ns), for when structure is guaranteed stable
+    if (Array.isArray(config)) {
+        let current = target;
+        for (const idx of config) {
+            if (!current || !current.children)
+                break;
+            current = current.children[idx];
+        }
+        return current instanceof Element ? current : undefined;
+    }
+    if (typeof config === 'object' && 'path' in config && !('qry' in config)) {
+        // Determine if this is from 'at' (no ID assignment) or 'withIds' with path (assigns ID + caches)
+        // When called from 'at', we skip ID/caching. When from 'withIds', we assign ID and cache.
+        // Distinguish by presence in the options — caller passes the merged map.
+        // For now: { path } without 'noId' → assign ID + cache (withIds behavior)
+        const rootNode = target.getRootNode?.() ?? target;
+        let current = target;
+        for (const idx of config.path) {
+            if (!current || !current.children)
+                break;
+            current = current.children[idx];
+        }
+        let el = current instanceof Element ? current : null;
+        // Validation: check if resolved element matches expected selector
+        if (config.expect) {
+            const didNotMatch = !el || !el.matches(config.expect);
+            if (didNotMatch) {
+                if (config.fallback) {
+                    el = target.querySelector?.(config.expect) ?? el;
+                }
+                // Fire-and-forget: log correction suggestion
+                const capturedConfig = config;
+                const capturedVarName = varName;
+                import('./withIdsCorrector.js').then(module => {
+                    module.logConfigCorrection(target, capturedVarName, capturedConfig);
+                }).catch(() => { });
+            }
+        }
+        if (!el)
+            return undefined;
+        // Assign ID for stability against future DOM mutations
+        let id = el.id;
+        if (!id) {
+            id = generateUniqueId(rootNode);
+            el.id = id;
+        }
+        return el;
+    }
     const rootNode = target.getRootNode?.() ?? target;
     // Get or create cache for this rootNode
     let cache = idCacheMap.get(rootNode);
@@ -50,28 +100,27 @@ export function resolveIdVariable(varName, target, withIds) {
         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
+        // Check cache first (getElementById lookups are cacheable — global to rootNode)
+        const cached = cache.get(varName);
+        if (cached) {
+            const cachedEl = cached.ref.deref();
+            if (cachedEl)
+                return cachedEl;
+            // 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;
+            }
+        }
         el = rootNode.getElementById?.(config) ?? null;
     }
     else {
-        // Object form: { qry } — run querySelector against target
+        // Object form: { qry } — run querySelector against target (target-relative, no cache)
         el = target.querySelector?.(config.qry) ?? null;
     }
     if (!el)
@@ -82,8 +131,10 @@ export function resolveIdVariable(varName, target, withIds) {
         id = generateUniqueId(rootNode);
         el.id = id;
     }
-    // Cache it
-    cache.set(varName, { id, ref: new WeakRef(el) });
+    // Cache only for string-form (getElementById) — not for qry form (target-relative)
+    if (typeof config === 'string') {
+        cache.set(varName, { id, ref: new WeakRef(el) });
+    }
     return el;
 }
 /**

package/resolveIdRef.ts

@@ -11,7 +11,7 @@
 /**
  * Configuration for a withIds entry.
  */
-export type WithIdConfig = string | { qry: string };
+export type WithIdConfig = string | { qry: string } | number[] | { path: number[]; expect?: string; fallback?: boolean };
 
 /**
  * Module-level cache: rootNode → Map<varName, { id, WeakRef }>
@@ -26,14 +26,15 @@ const idCounterMap = new WeakMap<object, number>();
 
 /**
  * Generate a unique ID within a rootNode.
- * Format: _ag0, _ag1, _ag2, ...
+ * Format: -ag:0, -ag:1, -ag:2, ...
+ * Starts with '-' and contains ':' to avoid collision with JS identifiers/globalThis properties.
  */
 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}`;
+        id = `-ag:${counter}`;
         counter++;
     } while (rootNode.getElementById?.(id));
     idCounterMap.set(rootNode, counter);
@@ -56,6 +57,57 @@ export function resolveIdVariable(
     const config = withIds[varName];
     if (config === undefined) return undefined;
 
+    // For 'at' option path-based configs (array or { path }), resolve directly from target — no ID, no caching
+    // These are target-relative and fast (~2-4ns), for when structure is guaranteed stable
+    if (Array.isArray(config)) {
+        let current: any = target;
+        for (const idx of config) {
+            if (!current || !current.children) break;
+            current = current.children[idx];
+        }
+        return current instanceof Element ? current : undefined;
+    }
+
+    if (typeof config === 'object' && 'path' in config && !('qry' in config)) {
+        // Determine if this is from 'at' (no ID assignment) or 'withIds' with path (assigns ID + caches)
+        // When called from 'at', we skip ID/caching. When from 'withIds', we assign ID and cache.
+        // Distinguish by presence in the options — caller passes the merged map.
+        // For now: { path } without 'noId' → assign ID + cache (withIds behavior)
+        const rootNode = target.getRootNode?.() ?? target;
+        let current: any = target;
+        for (const idx of config.path) {
+            if (!current || !current.children) break;
+            current = current.children[idx];
+        }
+        let el: Element | null = current instanceof Element ? current : null;
+
+        // Validation: check if resolved element matches expected selector
+        if (config.expect) {
+            const didNotMatch = !el || !el.matches(config.expect);
+            if (didNotMatch) {
+                if (config.fallback) {
+                    el = target.querySelector?.(config.expect) ?? el;
+                }
+                // Fire-and-forget: log correction suggestion
+                const capturedConfig = config;
+                const capturedVarName = varName;
+                import('./withIdsCorrector.js').then(module => {
+                    module.logConfigCorrection(target, capturedVarName, capturedConfig);
+                }).catch(() => {});
+            }
+        }
+
+        if (!el) return undefined;
+
+        // Assign ID for stability against future DOM mutations
+        let id = el.id;
+        if (!id) {
+            id = generateUniqueId(rootNode);
+            el.id = id;
+        }
+        return el;
+    }
+
     const rootNode = target.getRootNode?.() ?? target;
 
     // Get or create cache for this rootNode
@@ -65,29 +117,27 @@ export function resolveIdVariable(
         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
+        // Check cache first (getElementById lookups are cacheable — global to rootNode)
+        const cached = cache.get(varName);
+        if (cached) {
+            const cachedEl = cached.ref.deref();
+            if (cachedEl) return cachedEl;
+
+            // 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;
+            }
+        }
         el = rootNode.getElementById?.(config) ?? null;
     } else {
-        // Object form: { qry } — run querySelector against target
+        // Object form: { qry } — run querySelector against target (target-relative, no cache)
         el = target.querySelector?.(config.qry) ?? null;
     }
 
@@ -100,8 +150,10 @@ export function resolveIdVariable(
         el.id = id;
     }
 
-    // Cache it
-    cache.set(varName, { id, ref: new WeakRef(el) });
+    // Cache only for string-form (getElementById) — not for qry form (target-relative)
+    if (typeof config === 'string') {
+        cache.set(varName, { id, ref: new WeakRef(el) });
+    }
     return el;
 }
 

package/resolveValues.js

@@ -1,6 +1,22 @@
+/**
+ * resolveValues.ts — Async value resolution for path strings.
+ *
+ * Thin async wrapper around getValues that adds support for async protocol handlers.
+ * For synchronous-only use cases, import getValues/getValue directly for better performance.
+ *
+ * Re-exports ResolveValuesOptions for backward compatibility.
+ */
+import { getValue } from './getValues.js';
+// Re-export getValue as resolveValue for backward compatibility
+export { getValue as resolveValue };
+/**
+ * Checks if a string value looks like a protocol reference.
+ */
+function hasProtocol(value) {
+    return value.includes('://');
+}
 /**
  * Apply alias substitutions to a path string.
- * Replaces complete tokens between `?.` delimiters with their aliased values.
  */
 function applyAliases(path, aliasMap) {
     if (aliasMap.size === 0)
@@ -11,12 +27,8 @@ function applyAliases(path, aliasMap) {
 }
 /**
  * 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) {
@@ -25,44 +37,8 @@ function parseCachedPath(path) {
     }
     return parts;
 }
-/**
- * Resolves a protocol-prefixed value (e.g., 'globalThis://key?.path').
- *
- * 1. Extracts the protocol name (before '://')
- * 2. If the protocol isn't in the protocols map, returns the value unchanged (false positive)
- * 3. Extracts the key (between '://' and first '?.' or end of string)
- * 4. Calls the protocol handler with the key
- * 5. If there's a remaining '?.' path, resolves it against the handler's result
- */
-async function resolveProtocolValue(value, protocols, options) {
-    // Extract protocol name (before ://)
-    const protoEnd = value.indexOf('://');
-    const protocol = value.substring(0, protoEnd);
-    // Resolve via protocol handler
-    const handler = protocols[protocol];
-    if (!handler)
-        return value; // false flag — coincidentally looks like a protocol
-    const rest = value.substring(protoEnd + 3);
-    // Split at first ?. to separate key from path
-    const pathStart = rest.indexOf('?.');
-    const key = pathStart === -1 ? rest : rest.substring(0, pathStart);
-    const path = pathStart === -1 ? null : rest.substring(pathStart);
-    const resolved = await handler(key);
-    // If there's a remaining path, resolve it against the result
-    if (path) {
-        return resolveValue(path, resolved, options);
-    }
-    return resolved;
-}
-/**
- * Checks if a string value looks like a protocol reference.
- */
-function hasProtocol(value) {
-    return value.includes('://');
-}
 /**
  * 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;
@@ -76,12 +52,10 @@ function navigatePath(source, parts, withMethods) {
             if (typeof method === 'function') {
                 const nextPart = parts[i + 1];
                 if (nextPart !== undefined && !(withMethods.has(nextPart))) {
-                    // Call method with next segment as argument, consume it
                     current = method.call(current, nextPart);
                     i += 2;
                 }
                 else {
-                    // Consecutive methods or last segment — call with no args
                     current = method.call(current);
                     i++;
                 }
@@ -99,9 +73,26 @@ 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.
+ * Resolves a protocol-prefixed value asynchronously.
+ */
+async function resolveProtocolValue(value, protocols, options) {
+    const protoEnd = value.indexOf('://');
+    const protocol = value.substring(0, protoEnd);
+    const handler = protocols[protocol];
+    if (!handler)
+        return value;
+    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 = await handler(key);
+    if (path) {
+        return getValue(path, resolved, options);
+    }
+    return resolved;
+}
+/**
+ * Resolve path strings and protocol references within an array (async).
  */
 async function resolveArray(arr, source, aliasMap, withMethods, protocols, options) {
     const result = [];
@@ -133,47 +124,23 @@ async function resolveArray(arr, source, aliasMap, withMethods, protocols, optio
     return result;
 }
 /**
- * Resolve RHS path strings in a pattern object against a source object.
+ * Async 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 using optional chaining semantics.
- * Non-string values and strings not starting with `?.` pass through unchanged.
- *
- * Supports `withMethods` for calling methods during resolution and `aka` for
- * alias substitution, consistent with assignGingerly's LHS path handling.
- *
- * Special case: `'?.'` (empty path) resolves to the source object itself.
+ * Supports async protocol handlers (e.g., fetch, IndexedDB).
+ * For synchronous-only patterns, use `getValues` from 'assign-gingerly/getValues.js' instead.
  *
  * @param pattern - Object whose RHS values may contain `?.` path strings
  * @param source - Object to resolve paths against
- * @param options - Optional withMethods and aka for method calls and aliases
+ * @param options - Optional withMethods, aka, and protocol handlers
  * @returns New object with path strings replaced by resolved values
- *
- * @example
- * const result = resolveValues({
- *   hello: '?.myPropContainer?.stringProp',
- *   foo: '?.myFooString',
- *   literal: 42
- * }, source);
- *
- * @example
- * // With methods and aliases
- * const result = resolveValues({
- *   text: '?.q?..username?.textContent'
- * }, source, {
- *   withMethods: ['querySelector'],
- *   aka: { 'q': 'querySelector' }
- * });
  */
 export async function resolveValues(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
@@ -183,24 +150,17 @@ export async function resolveValues(pattern, source, options) {
     const result = {};
     for (const [key, value] of Object.entries(pattern)) {
         if (typeof value === 'string' && value.startsWith('?.')) {
-            // Apply aliases to the RHS path
             const aliased = applyAliases(value, aliasMap);
-            // Parse path with caching
             const parts = parseCachedPath(aliased);
-            // Navigate with method support
             result[key] = parts.length === 0 ? source : navigatePath(source, parts, withMethods);
         }
         else if (typeof value === 'string' && protocols && hasProtocol(value)) {
-            // Protocol-prefixed value — resolve asynchronously
             result[key] = await resolveProtocolValue(value, protocols, options);
         }
         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);
@@ -215,47 +175,3 @@ export async function resolveValues(pattern, source, options) {
     }
     return result;
 }
-/**
- * Resolve a single `?.`-delimited path string against a source object.
- *
- * This is a lighter-weight alternative to `resolveValues` when you only need
- * to resolve one path and don't want the overhead of creating wrapper objects.
- *
- * @param path - A `?.`-delimited path string (e.g., '?.behaviors?.command')
- * @param source - Object to resolve the path against
- * @param options - Optional withMethods and aka for method calls and aliases
- * @returns The resolved value, or undefined if any segment is nullish
- *
- * @example
- * const value = resolveValue('?.behaviors?.commandBehavior?.command', el);
- *
- * @example
- * const value = resolveValue('?.q?.myEl?.textContent', el, {
- *   withMethods: ['querySelector'],
- *   aka: { 'q': 'querySelector' }
- * });
- */
-export function resolveValue(path, source, options) {
-    if (!path.startsWith('?.'))
-        return path;
-    // Build alias map
-    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);
-    }
-    // Parse path with caching
-    const parts = parseCachedPath(aliased);
-    if (parts.length === 0)
-        return source;
-    // Build methods set
-    const withMethods = options?.withMethods
-        ? options.withMethods instanceof Set
-            ? options.withMethods
-            : new Set(options.withMethods)
-        : undefined;
-    return navigatePath(source, parts, withMethods);
-}