assign-gingerly 0.0.84 → 0.0.86

package/parseWithAttrs.js

@@ -3,19 +3,61 @@ import { resolveTemplate } from './resolve/resolveTemplate.js';
 // Module-level cache for parsed attribute values
 // Structure: Map<configKey, Map<attrValue, parsedValue>>
 const parseCache = new Map();
+/**
+ * Detects whether a value is a class-based parser constructor.
+ * Class parsers must have a `parse` method on their prototype.
+ */
+function isAttrParserConstructor(value) {
+    return typeof value === 'function' && !!value.prototype && 'parse' in value.prototype;
+}
+/**
+ * Instantiates a class parser and returns a wrapper function that calls its parse method.
+ * A new instance is created for each attribute parse (no cross-call caching).
+ */
+function instantiateClassParser(ParserCtor, options) {
+    const instance = new ParserCtor(options);
+    return (attrValue, context) => instance.parse(attrValue, context);
+}
+/**
+ * Looks up a named parser in the scoped (if available) then global registry.
+ */
+function lookupNamedParser(name, synthesizerElement) {
+    // Check scoped registry first (if synthesizerElement provided)
+    if (synthesizerElement) {
+        const scopedRegistry = getParserRegistry(synthesizerElement);
+        const scopedParser = scopedRegistry.get(name);
+        if (scopedParser) {
+            return scopedParser;
+        }
+    }
+    // Fallback to global registry
+    const globalParser = globalParserRegistry.get(name);
+    if (globalParser) {
+        return globalParser;
+    }
+    // Not found in either registry
+    throw new Error(`Parser "${name}" not found. ` +
+        `Checked ${synthesizerElement ? 'scoped registry and ' : ''}global registry.\n` +
+        `Ensure the parser is registered via:\n` +
+        `- <script type="emc-parser" src="..." parser-name="${name}">\n` +
+        `- registerParser(synthesizerElement, "${name}", parserFn)\n` +
+        `- globalParserRegistry.register("${name}", parserFn)`);
+}
 /**
  * Resolves a parser specification to an actual parser function
  * Supports:
  * - Inline functions (direct use)
- * - Named parsers from scoped registry (if synthesizerElement provided)
- * - Named parsers from global registry (fallback)
+ * - Named parser functions or class constructors from scoped/global registry (string form)
+ * - Named class parsers with options from the object form { name, options }
+ * - Custom element static methods via tuple form [elementName, methodName]
  *
- * @param parserSpec - Parser function or string reference
+ * @param parserSpec - Parser function, string reference, tuple, or object reference
  * @param synthesizerElement - Optional synthesizer element for scoped parser lookup
+ * @param parserOptions - Optional constructor options when a string resolves to a class parser
  * @returns The resolved parser function
  * @throws Error if parser cannot be resolved
  */
-function resolveParser(parserSpec, synthesizerElement) {
+function resolveParser(parserSpec, synthesizerElement, parserOptions) {
     // Undefined - no parser specified
     if (parserSpec === undefined) {
         return undefined;
@@ -24,31 +66,61 @@ function resolveParser(parserSpec, synthesizerElement) {
     if (typeof parserSpec === 'function') {
         return parserSpec;
     }
+    // Object form: { name, options }
+    if (parserSpec !== null &&
+        typeof parserSpec === 'object' &&
+        !Array.isArray(parserSpec) &&
+        'name' in parserSpec) {
+        const { name, options } = parserSpec;
+        const registered = lookupNamedParser(name, synthesizerElement);
+        if (isAttrParserConstructor(registered)) {
+            return instantiateClassParser(registered, options);
+        }
+        return registered;
+    }
     // String reference - resolve from scoped or global registry
     if (typeof parserSpec === 'string') {
-        // Check scoped registry first (if synthesizerElement provided)
-        if (synthesizerElement) {
-            const scopedRegistry = getParserRegistry(synthesizerElement);
-            const scopedParser = scopedRegistry.get(parserSpec);
-            if (scopedParser) {
-                return scopedParser;
-            }
+        const registered = lookupNamedParser(parserSpec, synthesizerElement);
+        if (isAttrParserConstructor(registered)) {
+            return instantiateClassParser(registered, parserOptions);
+        }
+        return registered;
+    }
+    // Tuple reference: [elementName, methodName]
+    if (Array.isArray(parserSpec) && parserSpec.length === 2) {
+        const [elementName, methodName] = parserSpec;
+        const Ctr = customElements.get(elementName);
+        if (!Ctr) {
+            throw new Error(`Cannot resolve parser [${elementName}, ${methodName}]: custom element "${elementName}" not found`);
         }
-        // Fallback to global registry
-        const globalParser = globalParserRegistry.get(parserSpec);
-        if (globalParser) {
-            return globalParser;
+        const method = Ctr[methodName];
+        if (typeof method !== 'function') {
+            throw new Error(`Cannot resolve parser [${elementName}, ${methodName}]: static method "${methodName}" not found on custom element "${elementName}"`);
         }
-        // Not found in either registry
-        throw new Error(`Parser "${parserSpec}" not found. ` +
-            `Checked ${synthesizerElement ? 'scoped registry and ' : ''}global registry.\n` +
-            `Ensure the parser is registered via:\n` +
-            `- <script type="emc-parser" src="..." parser-name="${parserSpec}">\n` +
-            `- registerParser(synthesizerElement, "${parserSpec}", parserFn)\n` +
-            `- globalParserRegistry.register("${parserSpec}", parserFn)`);
+        return method.bind(Ctr);
     }
     return undefined;
 }
+/**
+ * Serializes parser options for use in cache keys.
+ * RegExp values are normalized to their string representation.
+ */
+function serializeParserOptions(options) {
+    if (options === undefined || options === null) {
+        return '';
+    }
+    try {
+        return JSON.stringify(options, (_key, value) => {
+            if (value instanceof RegExp) {
+                return value.toString();
+            }
+            return value;
+        });
+    }
+    catch (_e) {
+        return String(options);
+    }
+}
 /**
  * Creates a cache key from an AttrConfig
  * Includes instanceOf and parser identifier to ensure correct cache hits
@@ -63,7 +135,19 @@ function getCacheKey(config) {
         parserStr = 'builtin';
     }
     else if (typeof config.parser === 'string') {
-        parserStr = `named:${config.parser}`;
+        const optionsStr = serializeParserOptions(config.parserOptions);
+        parserStr = `named:${config.parser}|options:${optionsStr}`;
+    }
+    else if (config.parser !== null &&
+        typeof config.parser === 'object' &&
+        !Array.isArray(config.parser) &&
+        'name' in config.parser) {
+        const ref = config.parser;
+        const optionsStr = serializeParserOptions(ref.options);
+        parserStr = `named:${ref.name}|options:${optionsStr}`;
+    }
+    else if (Array.isArray(config.parser)) {
+        parserStr = `tuple:${config.parser[0]},${config.parser[1]}`;
     }
     else {
         parserStr = 'custom';
@@ -328,7 +412,7 @@ export function parseWithAttrs(element, attrPatterns, allowUnprefixed, spawnCont
             }
             // For Boolean without valIfNull, fall through to parser
             else {
-                const parser = resolveParser(config.parser, synthesizerElement) || getDefaultParser(config.instanceOf);
+                const parser = resolveParser(config.parser, synthesizerElement, config.parserOptions) || getDefaultParser(config.instanceOf);
                 const parsedValue = callParser(parser, attrValue, parserContext);
                 const mapsTo = config.mapsTo ?? (key === 'base' ? '.' : key);
                 result[mapsTo] = parsedValue;
@@ -336,7 +420,7 @@ export function parseWithAttrs(element, attrPatterns, allowUnprefixed, spawnCont
             continue;
         }
         // Attribute exists - parse normally
-        const parser = resolveParser(config.parser, synthesizerElement) || getDefaultParser(config.instanceOf);
+        const parser = resolveParser(config.parser, synthesizerElement, config.parserOptions) || getDefaultParser(config.instanceOf);
         // Use cache if parseCache is specified
         const parsedValue = config.parseCache
             ? parseWithCache(attrValue, config, parser, parserContext)

package/parseWithAttrs.ts

@@ -1,4 +1,4 @@
-import { AttrPatterns, AttrConfig, ParserFunction, ParserContext, SpawnContext } from './types/assign-gingerly/types';
+import { AttrPatterns, AttrConfig, ParserFunction, ParserContext, SpawnContext, ParserSpec, AttrParserConstructor, NamedParserRef } from './types/assign-gingerly/types';
 import { globalParserRegistry, getParserRegistry } from './parserRegistry.js';
 import { resolveTemplate } from './resolve/resolveTemplate.js';
 
@@ -6,21 +6,79 @@ import { resolveTemplate } from './resolve/resolveTemplate.js';
 // Structure: Map<configKey, Map<attrValue, parsedValue>>
 const parseCache = new Map<string, Map<string, any>>();
 
+/**
+ * Detects whether a value is a class-based parser constructor.
+ * Class parsers must have a `parse` method on their prototype.
+ */
+function isAttrParserConstructor(
+  value: ParserFunction | AttrParserConstructor | undefined
+): value is AttrParserConstructor {
+  return typeof value === 'function' && !!value.prototype && 'parse' in value.prototype;
+}
+
+/**
+ * Instantiates a class parser and returns a wrapper function that calls its parse method.
+ * A new instance is created for each attribute parse (no cross-call caching).
+ */
+function instantiateClassParser(
+  ParserCtor: AttrParserConstructor,
+  options?: any
+): ParserFunction {
+  const instance = new ParserCtor(options);
+  return (attrValue, context) => instance.parse(attrValue, context);
+}
+
+/**
+ * Looks up a named parser in the scoped (if available) then global registry.
+ */
+function lookupNamedParser(
+  name: string,
+  synthesizerElement?: Element
+): ParserFunction | AttrParserConstructor {
+  // Check scoped registry first (if synthesizerElement provided)
+  if (synthesizerElement) {
+    const scopedRegistry = getParserRegistry(synthesizerElement);
+    const scopedParser = scopedRegistry.get(name);
+    if (scopedParser) {
+      return scopedParser;
+    }
+  }
+  
+  // Fallback to global registry
+  const globalParser = globalParserRegistry.get(name);
+  if (globalParser) {
+    return globalParser;
+  }
+  
+  // Not found in either registry
+  throw new Error(
+    `Parser "${name}" not found. ` +
+    `Checked ${synthesizerElement ? 'scoped registry and ' : ''}global registry.\n` +
+    `Ensure the parser is registered via:\n` +
+    `- <script type="emc-parser" src="..." parser-name="${name}">\n` +
+    `- registerParser(synthesizerElement, "${name}", parserFn)\n` +
+    `- globalParserRegistry.register("${name}", parserFn)`
+  );
+}
+
 /**
  * Resolves a parser specification to an actual parser function
  * Supports:
  * - Inline functions (direct use)
- * - Named parsers from scoped registry (if synthesizerElement provided)
- * - Named parsers from global registry (fallback)
+ * - Named parser functions or class constructors from scoped/global registry (string form)
+ * - Named class parsers with options from the object form { name, options }
+ * - Custom element static methods via tuple form [elementName, methodName]
  * 
- * @param parserSpec - Parser function or string reference
+ * @param parserSpec - Parser function, string reference, tuple, or object reference
  * @param synthesizerElement - Optional synthesizer element for scoped parser lookup
+ * @param parserOptions - Optional constructor options when a string resolves to a class parser
  * @returns The resolved parser function
  * @throws Error if parser cannot be resolved
  */
 function resolveParser(
-  parserSpec: ParserFunction | string | undefined,
-  synthesizerElement?: Element
+  parserSpec: ParserSpec | undefined,
+  synthesizerElement?: Element,
+  parserOptions?: any
 ): ParserFunction | undefined {
   // Undefined - no parser specified
   if (parserSpec === undefined) {
@@ -32,37 +90,71 @@ function resolveParser(
     return parserSpec;
   }
   
+  // Object form: { name, options }
+  if (
+    parserSpec !== null &&
+    typeof parserSpec === 'object' &&
+    !Array.isArray(parserSpec) &&
+    'name' in parserSpec
+  ) {
+    const { name, options } = parserSpec as NamedParserRef;
+    const registered = lookupNamedParser(name, synthesizerElement);
+    if (isAttrParserConstructor(registered)) {
+      return instantiateClassParser(registered, options);
+    }
+    return registered;
+  }
+  
   // String reference - resolve from scoped or global registry
   if (typeof parserSpec === 'string') {
-    // Check scoped registry first (if synthesizerElement provided)
-    if (synthesizerElement) {
-      const scopedRegistry = getParserRegistry(synthesizerElement);
-      const scopedParser = scopedRegistry.get(parserSpec);
-      if (scopedParser) {
-        return scopedParser;
-      }
+    const registered = lookupNamedParser(parserSpec, synthesizerElement);
+    if (isAttrParserConstructor(registered)) {
+      return instantiateClassParser(registered, parserOptions);
     }
-    
-    // Fallback to global registry
-    const globalParser = globalParserRegistry.get(parserSpec);
-    if (globalParser) {
-      return globalParser;
+    return registered;
+  }
+  
+  // Tuple reference: [elementName, methodName]
+  if (Array.isArray(parserSpec) && parserSpec.length === 2) {
+    const [elementName, methodName] = parserSpec;
+    const Ctr = customElements.get(elementName);
+    if (!Ctr) {
+      throw new Error(
+        `Cannot resolve parser [${elementName}, ${methodName}]: custom element "${elementName}" not found`
+      );
     }
-    
-    // Not found in either registry
-    throw new Error(
-      `Parser "${parserSpec}" not found. ` +
-      `Checked ${synthesizerElement ? 'scoped registry and ' : ''}global registry.\n` +
-      `Ensure the parser is registered via:\n` +
-      `- <script type="emc-parser" src="..." parser-name="${parserSpec}">\n` +
-      `- registerParser(synthesizerElement, "${parserSpec}", parserFn)\n` +
-      `- globalParserRegistry.register("${parserSpec}", parserFn)`
-    );
+    const method = (Ctr as any)[methodName];
+    if (typeof method !== 'function') {
+      throw new Error(
+        `Cannot resolve parser [${elementName}, ${methodName}]: static method "${methodName}" not found on custom element "${elementName}"`
+      );
+    }
+    return method.bind(Ctr);
   }
   
   return undefined;
 }
 
+/**
+ * Serializes parser options for use in cache keys.
+ * RegExp values are normalized to their string representation.
+ */
+function serializeParserOptions(options: any): string {
+  if (options === undefined || options === null) {
+    return '';
+  }
+  try {
+    return JSON.stringify(options, (_key, value) => {
+      if (value instanceof RegExp) {
+        return value.toString();
+      }
+      return value;
+    });
+  } catch (_e) {
+    return String(options);
+  }
+}
+
 /**
  * Creates a cache key from an AttrConfig
  * Includes instanceOf and parser identifier to ensure correct cache hits
@@ -77,7 +169,19 @@ function getCacheKey(config: AttrConfig<any>): string {
   if (config.parser === undefined) {
     parserStr = 'builtin';
   } else if (typeof config.parser === 'string') {
-    parserStr = `named:${config.parser}`;
+    const optionsStr = serializeParserOptions(config.parserOptions);
+    parserStr = `named:${config.parser}|options:${optionsStr}`;
+  } else if (
+    config.parser !== null &&
+    typeof config.parser === 'object' &&
+    !Array.isArray(config.parser) &&
+    'name' in config.parser
+  ) {
+    const ref = config.parser as NamedParserRef;
+    const optionsStr = serializeParserOptions(ref.options);
+    parserStr = `named:${ref.name}|options:${optionsStr}`;
+  } else if (Array.isArray(config.parser)) {
+    parserStr = `tuple:${config.parser[0]},${config.parser[1]}`;
   } else {
     parserStr = 'custom';
   }
@@ -390,7 +494,7 @@ export function parseWithAttrs<T = any>(
             }
             // For Boolean without valIfNull, fall through to parser
             else {
-                const parser = resolveParser(config.parser, synthesizerElement) || getDefaultParser(config.instanceOf);
+                const parser = resolveParser(config.parser, synthesizerElement, config.parserOptions) || getDefaultParser(config.instanceOf);
                 const parsedValue = callParser(parser, attrValue, parserContext);
                 const mapsTo = config.mapsTo ?? (key === 'base' ? '.' : key);
                 result[mapsTo as string] = parsedValue;
@@ -399,7 +503,7 @@ export function parseWithAttrs<T = any>(
         }
         
         // Attribute exists - parse normally
-        const parser = resolveParser(config.parser, synthesizerElement) || getDefaultParser(config.instanceOf);
+        const parser = resolveParser(config.parser, synthesizerElement, config.parserOptions) || getDefaultParser(config.instanceOf);
         
         // Use cache if parseCache is specified
         const parsedValue = config.parseCache 

package/parserRegistry.js

@@ -1,3 +1,5 @@
+import { SplitParser } from './SplitParser.js';
+import { ScopedParserRegistry } from './ScopedParserRegistry.js';
 /**
  * Registry for named parsers that can be referenced by string name
  * Enables JSON serialization of configs with custom parsers
@@ -7,7 +9,7 @@ export class ParserRegistry {
     /**
      * Register a parser with a given name
      * @param name - The name to register the parser under
-     * @param parser - The parser function
+     * @param parser - The parser function or class constructor
      */
     register(name, parser) {
         if (this.parsers.has(name)) {
@@ -18,7 +20,7 @@ export class ParserRegistry {
     /**
      * Get a parser by name
      * @param name - The name of the parser
-     * @returns The parser function or undefined if not found
+     * @returns The parser function, class constructor, or undefined if not found
      */
     get(name) {
         return this.parsers.get(name);
@@ -55,7 +57,6 @@ export const globalParserRegistry = new ParserRegistry();
 // Register common built-in parsers
 globalParserRegistry.register('timestamp', (v) => v ? new Date(v).getTime() : null);
 globalParserRegistry.register('date', (v) => v ? new Date(v) : null);
-globalParserRegistry.register('csv', (v) => v ? v.split(',').map((s) => s.trim()) : []);
 globalParserRegistry.register('int', (v) => v ? parseInt(v, 10) : null);
 globalParserRegistry.register('float', (v) => v ? parseFloat(v) : null);
 globalParserRegistry.register('boolean', (v) => v !== null);
@@ -69,7 +70,7 @@ globalParserRegistry.register('json', (v) => {
         throw new Error(`Failed to parse JSON: "${v}". Error: ${e}`);
     }
 });
-import { ScopedParserRegistry } from './ScopedParserRegistry.js';
+globalParserRegistry.register('splitter', SplitParser);
 /**
  * Symbol for storing scoped parser registry on synthesizer elements
  * Using Symbol.for ensures the same symbol is used across different versions of the package

package/parserRegistry.ts

@@ -1,18 +1,20 @@
-import { ParserFunction } from './types/assign-gingerly/types';
+import { ParserFunction, AttrParserConstructor } from './types/assign-gingerly/types';
+import { SplitParser } from './SplitParser.js';
+import { ScopedParserRegistry } from './ScopedParserRegistry.js';
 
 /**
  * Registry for named parsers that can be referenced by string name
  * Enables JSON serialization of configs with custom parsers
  */
 export class ParserRegistry {
-  private parsers = new Map<string, ParserFunction>();
+  private parsers = new Map<string, ParserFunction | AttrParserConstructor>();
   
   /**
    * Register a parser with a given name
    * @param name - The name to register the parser under
-   * @param parser - The parser function
+   * @param parser - The parser function or class constructor
    */
-  register(name: string, parser: ParserFunction): void {
+  register(name: string, parser: ParserFunction | AttrParserConstructor): void {
     if (this.parsers.has(name)) {
       console.warn(`Parser "${name}" already registered, overwriting`);
     }
@@ -22,9 +24,9 @@ export class ParserRegistry {
   /**
    * Get a parser by name
    * @param name - The name of the parser
-   * @returns The parser function or undefined if not found
+   * @returns The parser function, class constructor, or undefined if not found
    */
-  get(name: string): ParserFunction | undefined {
+  get(name: string): ParserFunction | AttrParserConstructor | undefined {
     return this.parsers.get(name);
   }
   
@@ -70,10 +72,6 @@ globalParserRegistry.register('date', (v: string | null) =>
   v ? new Date(v) : null
 );
 
-globalParserRegistry.register('csv', (v: string | null) => 
-  v ? v.split(',').map((s: string) => s.trim()) : []
-);
-
 globalParserRegistry.register('int', (v: string | null) => 
   v ? parseInt(v, 10) : null
 );
@@ -95,7 +93,7 @@ globalParserRegistry.register('json', (v: string | null) => {
   }
 });
 
-import { ScopedParserRegistry } from './ScopedParserRegistry.js';
+globalParserRegistry.register('splitter', SplitParser);
 
 /**
  * Symbol for storing scoped parser registry on synthesizer elements
@@ -129,7 +127,7 @@ export function getParserRegistry(synthesizerElement: Element): ScopedParserRegi
 export function registerParser(
   synthesizerElement: Element,
   name: string,
-  parser: ParserFunction
+  parser: ParserFunction | AttrParserConstructor
 ): void {
   const registry = getParserRegistry(synthesizerElement);
   registry.register(name, parser);

package/processHandlerCommands.js

@@ -5,16 +5,18 @@
  */
 import { resolveValues } from './resolve/resolveValues.js';
 import { getValues } from './resolve/getValues.js';
-import { evaluatePathWithMethods } from './assignGingerly.js';
+import { resolveLhsPath } from './utils/resolveLhsPath.js';
 import { findClassPrototypeInPath } from './utils/findClassPrototypeInPath.js';
 /**
  * Map of built-in handler names to their module paths.
  * These are auto-loaded on demand — no explicit import required.
+ *
+ * `join` moved to a synchronous ` =&` op (see syncOps/join.ts) — it never had
+ * side effects or anything to await, so it didn't belong behind this async pipeline.
  */
 const BUILT_IN_MAP = {
     'builtIns.lazyLoad': './handlers/lazyLoad.js',
     'builtIns.lazyLoadSwitch': './handlers/lazyLoadSwitch.js',
-    'builtIns.join': './handlers/join.js',
     'builtIns.microDataJoin': './handlers/microDataJoin.js',
     'builtIns.manageTemplateList': './handlers/manageTemplateList.js',
     'builtIns.rangeSelector': './handlers/rangeSelector.js',
@@ -98,59 +100,7 @@ export async function processHandlerCommands(target, handlerKeys, pattern, optio
             continue;
         // Resolve the LHS path, preserving parent + key for return-value assignment.
         // lhsParent[lhsKey] === lhsTarget (the current value at the path)
-        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 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;
-        }
+        const { lhsTarget, lhsParent, lhsKey } = resolveLhsPath(target, lhsPath, options);
         // Execute handlers sequentially, sharing the same lhsTarget
         for (const config of configs) {
             //return; //1.3ms

package/processHandlerCommands.ts

@@ -6,7 +6,7 @@
 
 import { resolveValues } from './resolve/resolveValues.js';
 import { getValues } from './resolve/getValues.js';
-import { evaluatePathWithMethods } from './assignGingerly.js';
+import { resolveLhsPath } from './utils/resolveLhsPath.js';
 import { findClassPrototypeInPath } from './utils/findClassPrototypeInPath.js';
 import type { PermissionProcessor } from './types/assign-gingerly/types.js';
 import type { AssignFromOptions, AssignFromHandlerConstructor } from './assignFromAsync.js';
@@ -14,11 +14,13 @@ import type { AssignFromOptions, AssignFromHandlerConstructor } from './assignFr
 /**
  * Map of built-in handler names to their module paths.
  * These are auto-loaded on demand — no explicit import required.
+ *
+ * `join` moved to a synchronous ` =&` op (see syncOps/join.ts) — it never had
+ * side effects or anything to await, so it didn't belong behind this async pipeline.
  */
 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',
     'builtIns.manageTemplateList': './handlers/manageTemplateList.js',
     'builtIns.rangeSelector': './handlers/rangeSelector.js',
@@ -121,55 +123,8 @@ export async function processHandlerCommands(
 
         // 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;
-        }
+        const { lhsTarget, lhsParent, lhsKey } = resolveLhsPath(target, lhsPath, options);
+
         // Execute handlers sequentially, sharing the same lhsTarget
         for (const config of configs) {
             //return; //1.3ms