assign-gingerly 0.0.57 → 0.0.59

package/processHandlerCommands.js

@@ -4,6 +4,7 @@
  * Dynamically imported only when ` =>` keys are detected in the pattern.
  */
 import { resolveValues } from './resolveValues.js';
+import { getValues } from './getValues.js';
 import { evaluatePathWithMethods } from './assignGingerly.js';
 import { isAllowedImportPath } from './isAllowedImportPath.js';
 /**
@@ -15,6 +16,7 @@ const BUILT_IN_MAP = {
     'builtIns.lazyLoadSwitch': './handlers/lazyLoadSwitch.js',
     'builtIns.join': './handlers/join.js',
     'builtIns.microDataJoin': './handlers/microDataJoin.js',
+    'builtIns.manageTemplateList': './handlers/manageTemplateList.js',
 };
 /**
  * Find a handler class in a dynamically imported module.
@@ -35,16 +37,27 @@ function findHandlerInModule(module) {
     }
     return undefined;
 }
+/**
+ * Cache for loaded built-in handler classes — avoids await on subsequent calls.
+ */
+const handlerCache = new Map();
 /**
  * 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) {
+    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;
 }
 /**
  * Resolve a handler from options.handlers (class constructor or import path).
@@ -157,27 +170,41 @@ export async function processHandlerCommands(target, handlerKeys, pattern, optio
         }
         // 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 = {};
+            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/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;
 }
 
 /**
@@ -107,6 +119,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 +191,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/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);
-}