@cocreate/utils 1.42.1 → 1.44.0

package/src/operators.js

@@ -16,14 +16,38 @@ const mathFunctions = {
 /**
  * Reference class used by safeParse to track object properties for assignments.
  * Prevents dot-notation from just returning values when we need to assign to them (e.g., el.value = 5)
+ * Upgraded to handle array contexts: if the object is an array, properties map across all items natively.
  */
 class Ref {
     constructor(obj, prop) {
         this.obj = obj;
         this.prop = prop;
+        
+        // Ensure we recognize standard arrays AND DOM collections (NodeList/HTMLCollection)
+        let isList = Array.isArray(obj) || 
+                     (typeof NodeList !== "undefined" && obj instanceof NodeList) || 
+                     (typeof HTMLCollection !== "undefined" && obj instanceof HTMLCollection);
+                     
+        this.isArrayContext = isList && !(prop in obj);
+        
+        if (this.isArrayContext && !Array.isArray(this.obj)) {
+            this.obj = Array.from(this.obj);
+        }
+    }
+    get() { 
+        if (this.isArrayContext) {
+            // Return the raw Array of extracted properties so the user can use .join() or other array methods
+            let res = this.obj.map(item => item ? item[this.prop] : undefined);
+            return res;
+        }
+        let res = this.obj ? this.obj[this.prop] : undefined; 
+        return res; 
     }
-    get() { return this.obj ? this.obj[this.prop] : undefined; }
     set(val) { 
+        if (this.isArrayContext) {
+            this.obj.forEach(item => { if (item) item[this.prop] = val; });
+            return val;
+        }
         if (this.obj) this.obj[this.prop] = val; 
         return val; 
     }
@@ -59,7 +83,7 @@ function safeParse(expression, registry = new Map()) {
             consume();
             let right = unref(parseAssignment());
             if (left instanceof Ref) {
-                return left.set(right); // Assign value to the actual object property
+                return left.set(right); // Assign value to the actual object property (or all properties in an array)
             }
             return right;
         }
@@ -183,17 +207,76 @@ function safeParse(expression, registry = new Map()) {
             val = undefined;
         }
 
-        if (path.length === 1) return val;
+        if (path.length === 1) {
+            // Support explicit call for root variables
+            if (peek() === "(" && typeof val === "function") {
+                consume();
+                let args = [];
+                if (peek() !== ")") {
+                    args.push(unref(parse()));
+                    while (peek() === ",") {
+                        consume();
+                        args.push(unref(parse()));
+                    }
+                }
+                if (peek() === ")") consume();
+                return val(...args);
+            }
+            return val;
+        }
 
         for (let i = 1; i < path.length - 1; i++) {
             if (val !== null && val !== undefined) {
-                val = val[path[i]];
+                // Support deep traversal across arrays
+                let isList = Array.isArray(val) || (typeof NodeList !== "undefined" && val instanceof NodeList) || (typeof HTMLCollection !== "undefined" && val instanceof HTMLCollection);
+                if (isList && !(path[i] in val)) {
+                    val = Array.from(val).map(item => item ? item[path[i]] : undefined);
+                } else {
+                    val = val[path[i]];
+                }
             } else {
                 return undefined;
             }
         }
 
-        return new Ref(val, path[path.length - 1]);
+        let ref = new Ref(val, path[path.length - 1]);
+
+        // Support explicit method calls (e.g., obj.method(arg))
+        if (peek() === "(") {
+            consume();
+            let args = [];
+            if (peek() !== ")") {
+                args.push(unref(parse()));
+                while (peek() === ",") {
+                    consume();
+                    args.push(unref(parse()));
+                }
+            }
+            if (peek() === ")") consume();
+            
+            // Map the method call across all items if it's an array context
+            if (ref.isArrayContext) {
+                let results = ref.obj.map(item => {
+                    let func = item ? item[ref.prop] : undefined;
+                    if (func !== undefined && typeof func !== "function") {
+                        console.warn(`Operator Engine: '${ref.prop}' is not a valid function on the target element.`);
+                    }
+                    let res = typeof func === "function" ? func.apply(item, args) : undefined;
+                    return res;
+                });
+                return results; // Return the natively mapped Array so user can process it!
+            } else {
+                let func = ref.obj ? ref.obj[ref.prop] : undefined;
+                if (typeof func === "function") {
+                    let res = func.apply(ref.obj, args);
+                    return res;
+                } else {
+                    console.warn(`Operator Engine: Method '${ref.prop}' does not exist on the target object.`);
+                }
+            }
+        }
+
+        return ref;
     }
 
     try {
@@ -212,10 +295,10 @@ const customOperators = new Map(
     Object.entries({
         $organization_id: () => localStorage.getItem("organization_id"),
         $user_id: () => localStorage.getItem("user_id"),
-        $clientId: () => localStorage.getItem("clientId"),
+        $client_id: () => localStorage.getItem("clientId"),
         $session_id: () => localStorage.getItem("session_id"),
-        $this: (element) => element,
-        $value: (element) => element.getValue() || "",
+        $this: function() { return this; },
+        $value: function() { return this && typeof this.getValue === 'function' ? this.getValue() : ""; },
         $innerWidth: () => window.innerWidth,
         $innerHeight: () => window.innerHeight,
         $href: () => window.location.href.replace(/\/$/, ""),
@@ -229,12 +312,52 @@ const customOperators = new Map(
         $subdomain: () => getSubdomain() || "",
         $object_id: () => ObjectId().toString(),
         "ObjectId()": () => ObjectId().toString(),
-        // Unwrap query results if only one element is found
-        $query: (element, args) => {
-            const results = queryElements({ element, selector: args });
-            return results.length === 1 ? results[0] : results;
+        
+        // Unwrap query results correctly: Returns only the single first item
+        $query: function(selector) {
+            let element = this;
+            if (typeof selector === 'string') {
+                selector = selector.trim();
+                // Strip quotes out of the selector in case they were passed (e.g., $query('#id1'))
+                if ((selector.startsWith("'") && selector.endsWith("'")) || 
+                    (selector.startsWith('"') && selector.endsWith('"'))) {
+                    selector = selector.slice(1, -1);
+                }
+            }
+            try {
+                let results = queryElements({ element, selector });
+                if (!results || results.length === 0) return undefined; 
+                return results[0]; // Strict single item return
+            } catch (error) {
+                console.warn(`Operator Engine: Invalid $query selector => "${selector}"`, error);
+                return undefined; 
+            }
+        },
+        // Unwrap query results correctly: Always returns an array 
+        $queryAll: function(selector) {
+            let element = this;
+            if (typeof selector === 'string') {
+                selector = selector.trim();
+                // Strip quotes out of the selector in case they were passed (e.g., $queryAll('.items'))
+                if ((selector.startsWith("'") && selector.endsWith("'")) || 
+                    (selector.startsWith('"') && selector.endsWith('"'))) {
+                    selector = selector.slice(1, -1);
+                }
+                
+                // Safely ignore queries targeting $document to prevent querySelector crashes
+                if (selector.includes('$document')) return [];
+            }
+            try {
+                let results = queryElements({ element, selector });
+                if (!results || results.length === 0) return []; 
+                // Always cast to array so Ref mapping handles methods uniformly
+                return Array.from(results);
+            } catch (error) {
+                console.warn(`Operator Engine: Invalid $queryAll selector => "${selector}"`, error);
+                return []; 
+            }
         },
-        $eval: (element, args, context) => safeParse(args, context.registry),
+        $eval: function(expression) { return safeParse(expression); },
         $relativePath: () => {
             let currentPath = window.location.pathname.replace(/\/[^\/]*$/, ""); 
             let depth = currentPath.split("/").filter(Boolean).length;
@@ -245,29 +368,28 @@ const customOperators = new Map(
             if (path.split("/").pop().includes(".")) path = path.replace(/\/[^\/]+$/, "/");
             return path === "/" ? "" : path;
         },
-        $param: (element, args) => args,
-        $getObjectValue: (element, args) => {
-            if (Array.isArray(args) && args.length >= 2) return getValueFromObject(args[0], args[1]);
-            return "";
+        $param: function(...args) { return args.length === 1 ? args[0] : args; },
+        $getObjectValue: function(obj, key) {
+            return getValueFromObject(obj, key);
+        },
+        $setValue: function(...args) {
+            return typeof this.setValue === 'function' ? this.setValue(...args) || "" : "";
         },
-        $setValue: (element, args) => element.setValue(...args) || "",
         $true: () => true,
         $false: () => false,
-        $parse: (element, args) => {
-            let value = args || "";
+        $parse: function(value = "") {
             try { return JSON.parse(value); } catch (e) { return value; }
         },
-        $numberFormat: (element, args) => {
-            let number = parseFloat(args[0]);
-            if (!Array.isArray(args)) args = [args];
+        $numberFormat: function() {
+            let args = Array.from(arguments);
             const locale = args[0] || undefined;
             const options = args[1] || {};
             const numCandidate = args[2] !== undefined ? args[2] : args[0];
-            number = parseFloat(numCandidate);
+            let number = parseFloat(numCandidate);
             if (isNaN(number)) return String(numCandidate ?? "");
             return new Intl.NumberFormat(locale, options).format(number);
         },
-        $uid: (element, args) => uid(args[0]) || "",
+        $uid: function(prefix) { return uid(prefix) || ""; },
     })
 );
 
@@ -282,62 +404,108 @@ const isConstructor = (func, name) => {
     return false;
 };
 
-const findBareOperatorInPath = (path) => {
-    const trimmedPath = path.trim();
-    const match = trimmedPath.match(/^(\$[\w\-]+)/);
-    if (match) {
-        const key = match[1];
-        const remaining = trimmedPath.substring(key.length);
-        if (remaining.length === 0 || /^\s|\[|\./.test(remaining)) return key;
-    }
-    return null;
-}
+const findInnermostOperator = (expression) => {
+    let parens = [];
+    let stack = [];
+    let inSQ = false, inDQ = false;
 
-const findInnermostFunctionCall = (expression) => {
-    let balance = 0, deepestStart = -1, deepestEnd = -1, deepestBalance = -1;
-    let inSingleQuote = false, inDoubleQuote = false;
+    // 1. Capture all parenthesis pairs accurately (The Parenthesis-First "Animals" boundary)
     for (let i = 0; i < expression.length; i++) {
         const char = expression[i];
-        if (char === '"' && !inSingleQuote) { inDoubleQuote = !inDoubleQuote; continue; }
-        else if (char === "'" && !inDoubleQuote) { inSingleQuote = !inDoubleQuote; continue; }
-        if (inSingleQuote || inDoubleQuote) continue;
+        if (char === '\\') { i++; continue; }
+        if (char === '"' && !inSQ) inDQ = !inDQ;
+        if (char === "'" && !inDQ) inSQ = !inSQ;
+        if (inSQ || inDQ) continue;
+
         if (char === '(') {
-            balance++;
-            if (balance > deepestBalance) { deepestBalance = balance; deepestStart = i; deepestEnd = -1; }
+            stack.push(i);
         } else if (char === ')') {
-            if (balance === deepestBalance) deepestEnd = i;
-            balance--;
+            if (stack.length > 0) {
+                const start = stack.pop();
+                parens.push({ start: start, end: i, depth: stack.length });
+            }
         }
     }
-    if (deepestStart === -1 || deepestEnd === -1 || deepestEnd <= deepestStart) return null;
-    const rawArgs = expression.substring(deepestStart + 1, deepestEnd).trim();
-    let operatorStart = -1, nonWhitespaceFound = false;
-    for (let i = deepestStart - 1; i >= 0; i--) {
-        const char = expression[i];
-        if (!nonWhitespaceFound) { if (/\s/.test(char)) continue; nonWhitespaceFound = true; }
-        if (!/[\w\-\$]/.test(char)) { operatorStart = i + 1; break; }
-        operatorStart = i;
-    }
-    if (operatorStart === -1) operatorStart = 0;
-    const operatorNameCandidate = expression.substring(operatorStart, deepestStart).trim();
-    if (/^\$[\w\-]+$/.test(operatorNameCandidate) || customOperators.has(operatorNameCandidate)) {
-        return { operator: operatorNameCandidate, args: rawArgs, fullMatch: expression.substring(operatorStart, deepestEnd + 1) };
-    }
-    return null;
-};
 
-const findInnermostOperator = (expression) => {
+    // Sort by depth descending (innermost first), then by start descending (right-most first)
+    parens.sort((a, b) => b.depth - a.depth || b.start - a.start);
+
     function stripParentheses(str) {
-        let result = str;
-        if (result.startsWith("(")) result = result.substring(1);
-        if (result.endsWith(")")) result = result.substring(0, result.length - 1);
+        let result = str.trim();
+        if (result.startsWith("(") && result.endsWith(")")) {
+            let balance = 0;
+            let isMatchedPair = true;
+            for (let i = 0; i < result.length - 1; i++) {
+                if (result[i] === '(') balance++;
+                else if (result[i] === ')') balance--;
+                if (balance === 0) { isMatchedPair = false; break; }
+            }
+            if (isMatchedPair && balance === 1) {
+                return result.substring(1, result.length - 1);
+            }
+        }
         return result;
     }
-    const functionCall = findInnermostFunctionCall(expression);
-    if (functionCall) return { operator: functionCall.operator, args: stripParentheses(functionCall.args), rawContent: functionCall.args, fullMatch: functionCall.fullMatch };
-    const rawContent = expression.trim(), innermostOperator = findBareOperatorInPath(rawContent);
-    if (innermostOperator) return { operator: innermostOperator, args: stripParentheses(rawContent.substring(innermostOperator.length).trim()), rawContent: rawContent };
-    return { operator: null, args: stripParentheses(rawContent), rawContent: rawContent };
+
+    // 2. Look to the left of the innermost parentheses to find the keyword operator
+    for (const p of parens) {
+        // We safely isolate ONLY what is inside the parens, bypassing the need for string replacements
+        const insideParens = expression.substring(p.start + 1, p.end).trim();
+        const leftPart = expression.substring(0, p.start);
+
+        // Check for an operator keyword directly attached to the left of the `(`
+        const match = leftPart.match(/(?:^|[^\w\$])(\$[\w\-]+|ObjectId\b)\s*$/);
+        
+        if (match) {
+            let opName = match[1] === 'ObjectId' ? 'ObjectId()' : match[1];
+            if (customOperators.has(opName) || /^\$[\w\-]+$/.test(opName)) {
+                // Pinpoint exactly where the operator string began
+                const spacesMatch = leftPart.match(/\s*$/);
+                const spacesAtEnd = spacesMatch ? spacesMatch[0].length : 0;
+                const fullMatchStart = match.index + match[0].length - match[1].length - spacesAtEnd;
+                
+                const resultBlock = { 
+                    operator: opName, 
+                    args: insideParens, // Perfectly isolated arguments, handling nested chains
+                    fullMatch: expression.substring(fullMatchStart, p.end + 1),
+                    rawContent: expression.substring(fullMatchStart, p.end + 1)
+                };
+                return resultBlock;
+            }
+        }
+    }
+
+    // 3. Fallback: Find bare operators (like $this) that have no parentheses attached
+    const bareRegex = /(?:^|[^\w\$])(\$[\w\-]+|ObjectId\b)/g;
+    let bareMatch;
+    let bareCandidates = [];
+    
+    while ((bareMatch = bareRegex.exec(expression)) !== null) {
+        let possibleOp = bareMatch[1];
+        let opName = possibleOp === 'ObjectId' ? 'ObjectId()' : possibleOp;
+        
+        // Ensure it isnt followed by a `(` (because if it was, it would have been caught above)
+        let remainder = expression.substring(bareMatch.index + bareMatch[0].length);
+        if (!/^\s*\(/.test(remainder)) {
+            if (customOperators.has(opName) || /^\$[\w\-]+$/.test(opName)) {
+                 bareCandidates.push({
+                     operator: opName, 
+                     args: undefined, 
+                     rawContent: possibleOp, 
+                     fullMatch: possibleOp,
+                     start: bareMatch.index + (bareMatch[0].length - possibleOp.length)
+                 });
+            }
+        }
+    }
+    
+    if (bareCandidates.length > 0) {
+        bareCandidates.sort((a, b) => b.start - a.start);
+        return bareCandidates[0];
+    }
+
+    const defaultFallback = { operator: null, args: stripParentheses(expression), rawContent: expression.trim() };
+    return defaultFallback;
 };
 
 function processOperators(element, value, exclude = [], parent, params = [], objectRegistry = new Map()) {
@@ -383,11 +551,40 @@ function processOperators(element, value, exclude = [], parent, params = [], obj
         if (processedValue === textToReplace) { processedValue = replacement; break; }
         processedValue = processedValue.replace(textToReplace, replacement);
     }
-    for (const [token, originalText] of unresolvedTokens.entries()) processedValue = processedValue.replace(token, originalText);
+    
+    // Restore unresolved exclusions (Reverse-order replaces ensure perfectly unnested loops)
     if (typeof processedValue === "string") {
+        let keys = Array.from(unresolvedTokens.keys()).reverse();
+        for (const token of keys) {
+            processedValue = processedValue.replaceAll(token, unresolvedTokens.get(token));
+        }
+        
+        // Native method and property chaining evaluation
+        // 1. If the ENTIRE string is a pure method/property chain (e.g. __OBJ_0__.getValue() )
+        const exactMethodMatch = processedValue.match(/^__OBJ_\d+__(?:\.[a-zA-Z0-9_]+)+(?:\(.*\))?$/);
+        if (exactMethodMatch) {
+            const parsed = safeParse(processedValue, objectRegistry);
+            // DO NOT LEAK tokens to the UI. Fallback to "" instead of the processedValue placeholder if it fails.
+            return parsed !== null && parsed !== undefined ? parsed : ""; 
+        }
+        
+        // 2. Unpack pure object variables
         const exactMatch = processedValue.match(/^__OBJ_(\d+)__$/);
-        if (exactMatch && objectRegistry.has(processedValue)) processedValue = objectRegistry.get(processedValue);
+        if (exactMatch && objectRegistry.has(processedValue)) {
+            processedValue = objectRegistry.get(processedValue);
+        } else {
+            // 3. Inline interpolation for methods/properties (e.g., "User clicked __OBJ_0__.getValue()")
+            const objRegex = /__OBJ_\d+__(?:\.[a-zA-Z0-9_]+)+(?:\([^)]*\))?/g;
+            if (processedValue.includes("__OBJ_")) {
+                processedValue = processedValue.replace(objRegex, (match) => {
+                    const parsed = safeParse(match, objectRegistry);
+                    // DO NOT LEAK tokens to the UI. Fallback to "" instead of the match placeholder if it fails.
+                    return parsed !== null && parsed !== undefined ? parsed : "";
+                });
+            }
+        }
     }
+    
     if (hasPromise) return { value: processedValue, params, objectRegistry };
     return processedValue;
 }
@@ -406,16 +603,27 @@ function resolveOperator(element, operator, args, parent, params, objectRegistry
     if (args && typeof args === "string" && args.includes("$")) {
         args = processOperators(element, args, [], operator, params, objectRegistry);
     }
+    
     let targetElements = element ? [element] : [];
     if (args && typeof args === "string") {
         const objMatch = args.match(/^__OBJ_(\d+)__$/);
         if (objMatch && objectRegistry.has(args)) {
-            targetElements = [objectRegistry.get(args)];
-        } else if (!customOperators.has(operator)) {
-            targetElements = queryElements({ element, selector: args });
+            let registeredVal = objectRegistry.get(args);
+            // Ensure unrolled array natively
+            let isList = Array.isArray(registeredVal) || (typeof NodeList !== "undefined" && registeredVal instanceof NodeList) || (typeof HTMLCollection !== "undefined" && registeredVal instanceof HTMLCollection);
+            targetElements = isList ? Array.from(registeredVal) : [registeredVal];
+        } else if (!customOperators.has(operator) &&  (operator === "$query")) {
+            let qResults = queryElements({ element, selector: args });
+            if (!qResults) {
+                targetElements = [];
+            } else {
+                let isList = Array.isArray(qResults) || (typeof NodeList !== "undefined" && qResults instanceof NodeList) || (typeof HTMLCollection !== "undefined" && qResults instanceof HTMLCollection);
+                targetElements = isList ? Array.from(qResults) : [qResults];
+            }
             if (!targetElements.length) return undefined;
         }
     }
+    
     let value = processValues(targetElements, operator, args, parent, objectRegistry);
     if (value && typeof value === "string" && value.includes("$")) {
         value = processOperators(element, value, [], parent, params, objectRegistry);
@@ -425,31 +633,184 @@ function resolveOperator(element, operator, args, parent, params, objectRegistry
 
 function processValues(elements, operator, args, parent, objectRegistry) {
     let customOp = customOperators.get(operator);
-    let aggregatedString = "";
+
+    let results = [];
     let hasValidProperty = customOp ? true : false;
-    const context = { registry: objectRegistry, element: elements[0] };
+    
     for (const el of elements) {
         if (!el) continue;
         let rawValue = customOp;
         const propName = customOp ? null : operator.substring(1);
         if (!customOp) {
-            if (propName in el) { hasValidProperty = true; rawValue = el[propName]; }
-            else continue;
+            if (propName in el) { 
+                hasValidProperty = true; 
+                rawValue = el[propName]; 
+            }
+            else {
+                continue;
+            }
+        }
+
+        // --- 1. RECONSTRUCT THE "GHOST" STRUCTURE (Tokens -> Actual JS Types) ---
+        let preparedArgs = [];
+        const originalWasArray = Array.isArray(args);
+        const hasArgs = originalWasArray || args !== undefined;
+
+        if (originalWasArray) {
+            preparedArgs = Array.from(args);
+        } else if (typeof args === "string") {
+            if (args === "") {
+                preparedArgs = [""]; // Explicitly retain empty string arguments
+            } else {
+                // Smart parse for comma-separated arguments respecting strings and brackets
+                let parsedArgs = [];
+                let currentArg = '';
+                let inSQ = false, inDQ = false;
+                let depth = 0;
+                
+                for (let i = 0; i < args.length; i++) {
+                    const char = args[i];
+                    if (char === '\\') { 
+                        currentArg += char; 
+                        if (i + 1 < args.length) currentArg += args[++i]; 
+                        continue; 
+                    }
+                    if (char === "'" && !inDQ) inSQ = !inSQ;
+                    if (char === '"' && !inSQ) inDQ = !inDQ;
+                    
+                    // Keep track of brackets and parens grouping so we don't accidentally split them inside
+                    if (!inSQ && !inDQ) {
+                        if (char === '(' || char === '[' || char === '{') depth++;
+                        else if (char === ')' || char === ']' || char === '}') depth--;
+                    }
+                    
+                    if (char === ',' && !inSQ && !inDQ && depth === 0) {
+                        parsedArgs.push(currentArg.trim());
+                        currentArg = '';
+                    } else {
+                        currentArg += char;
+                    }
+                }
+                if (currentArg.trim() !== "") parsedArgs.push(currentArg.trim());
+
+                // Reconstruct actual JavaScript types
+                preparedArgs = parsedArgs.map(arg => {
+                    // 1. Direct object token match (brings back exactly the array, obj, or variable!)
+                    if (/^__OBJ_\d+__$/.test(arg) && objectRegistry && objectRegistry.has(arg)) {
+                        return objectRegistry.get(arg);
+                    }
+                    
+                    // 2. Numbers
+                    if (!isNaN(arg) && arg.trim() !== "") {
+                        return Number(arg);
+                    }
+                    
+                    // 3. Booleans and Null
+                    if (arg === "true") return true;
+                    if (arg === "false") return false;
+                    if (arg === "null") return null;
+                    if (arg === "undefined") return undefined;
+                    
+                    // 4. Strings with quotes (strip outer quotes reliably)
+                    if ((arg.startsWith("'") && arg.endsWith("'")) || (arg.startsWith('"') && arg.endsWith('"'))) {
+                        let unquoted = arg.slice(1, -1);
+                        if (unquoted.includes("__OBJ_")) {
+                            return unquoted.replace(/__OBJ_\d+__/g, (match) => {
+                                if (objectRegistry && objectRegistry.has(match)) {
+                                    let val = objectRegistry.get(match);
+                                    return typeof val === "object" ? JSON.stringify(val) : String(val);
+                                }
+                                return match;
+                            });
+                        }
+                        return unquoted;
+                    }
+                    
+                    // 5. Inline token replacements for mixed strings (e.g., "Welcome __OBJ_1__")
+                    if (typeof arg === "string" && arg.includes("__OBJ_")) {
+                        return arg.replace(/__OBJ_\d+__/g, (match) => {
+                            if (objectRegistry && objectRegistry.has(match)) {
+                                let val = objectRegistry.get(match);
+                                return typeof val === "object" ? JSON.stringify(val) : String(val);
+                            }
+                            return match;
+                        });
+                    }
+                    
+                    // Fallback literal string
+                    return arg;
+                });
+            }
+        } else if (hasArgs) {
+            preparedArgs = [args];
+        }
+
+        // Extra safety: Make sure tokens passed directly as Array items are mapped
+        if (originalWasArray) {
+            preparedArgs = preparedArgs.map(a => {
+                if (typeof a === 'string' && /^__OBJ_\d+__$/.test(a) && objectRegistry && objectRegistry.has(a)) {
+                    return objectRegistry.get(a);
+                }
+                return a;
+            });
+        }
+
+        // Create the resolvedArgs shape the engine natively expects
+        let resolvedArgs;
+        if (originalWasArray || preparedArgs.length > 1) {
+            resolvedArgs = preparedArgs;
+        } else if (preparedArgs.length === 1) {
+            resolvedArgs = preparedArgs[0];
+        } else {
+            resolvedArgs = undefined;
         }
+
+        // --- 2. EXECUTE OR ASSIGN ---
         if (typeof rawValue === "function") {
-            if (customOp) rawValue = Array.isArray(args) ? rawValue(el, ...args, context) : rawValue(el, args, context);
-            else {
-                if (isConstructor(rawValue, propName)) rawValue = Array.isArray(args) ? new rawValue(...args) : new rawValue(args);
-                else rawValue = Array.isArray(args) ? rawValue.apply(el, args) : rawValue.call(el, args);
+            try {
+                if (isConstructor(rawValue, propName)) {
+                    if (Array.isArray(resolvedArgs)) {
+                        rawValue = new rawValue(...resolvedArgs);
+                    } else if (resolvedArgs !== undefined) {
+                        rawValue = new rawValue(resolvedArgs);
+                    } else {
+                        rawValue = new rawValue();
+                    }
+                } else {
+                    if (Array.isArray(resolvedArgs)) {
+                        rawValue = rawValue.apply(el, resolvedArgs); // Bind context correctly to element!
+                    } else if (resolvedArgs !== undefined) {
+                        rawValue = rawValue.call(el, resolvedArgs);
+                    } else {
+                        rawValue = rawValue.call(el);
+                    }
+                }
+            } catch (err) {
+                console.warn(`Operator Engine: Failed to execute method or operator "${operator}"`, err);
+                continue; // Skip this element's value if execution failed
+            }
+        } else if (hasArgs && propName) {
+            // PROPERTY ASSIGNMENT
+            try {
+                el[propName] = resolvedArgs;
+                rawValue = el[propName]; // Read it back to ensure success/validate formatting
+            } catch (err) {
+                console.warn(`Operator Engine: Failed to assign property "${propName}"`, err);
+                continue;
             }
         }
-        if (parent === "$param") { if (rawValue !== undefined && rawValue !== null) return rawValue; }
-        else {
-            if (rawValue instanceof Promise || (typeof rawValue === "object" && rawValue !== null) || typeof rawValue === "function") return rawValue;
-            aggregatedString += String(rawValue ?? "");
+
+        if (rawValue !== undefined && rawValue !== null) {
+            results.push(rawValue);
         }
     }
-    return hasValidProperty ? aggregatedString : undefined;
+    
+    if (!hasValidProperty) return undefined;
+    if (results.length === 0) return ""; // Explicitly return empty string if elements are found but have no matches to prevent Token masking.
+    
+    // Return the array wrapper (even for length 1) to ensure .map array methods remain accessible!
+    if (results.length === 1) return results[0];
+    return results;
 }
 
 function getSubdomain() {
@@ -458,4 +819,4 @@ function getSubdomain() {
     return null;
 }
 
-export { processOperators, processOperatorsAsync, customOperators };
+export { processOperators, processOperatorsAsync, customOperators, safeParse };